12 KiB
技术上下文
后端技术栈(Go 1.25,module go-sms)
| 类别 | 选型 |
|---|---|
| Web 框架 | gin v1.10 |
| ORM | gorm v1.30 + gormigrate v2(迁移 v1~v19);驱动 mysql / glebarez sqlite(单测) |
| 消息队列 | Kafka(IBM/sarama v1.43)——四核心 Topic:submit/report 等,16 分区 |
| 缓存/锁 | redis/go-redis v9(single/cluster)、freecache(本地)、etcd client v3 |
| 鉴权 | golang-jwt/v5 + casbin v2(gorm-adapter,RBAC+二级权限) |
| 可观测 | prometheus/client_golang、OTel(otlptracehttp)、zap + lumberjack 日志轮转 |
| 存储 | MySQL 8.0(36 表主库)、ClickHouse 24.3(历史归档规划)、RustFS 1.0.5(对象存储,2026-11-13 起;原 MinIO 社区版收费化替换;Apache 2.0/S3 API 兼容;客户端仍 minio-go SDK 通用 S3 面零改动) |
| 其他 | excelize(XLSX)、miniredis(测试)、websocket |
前端技术栈(web/,package name hwsms-web)
| 类别 | 选型 |
|---|---|
| 框架 | Vue 3.4 + TypeScript 5.4(setup 语法) |
| UI | Element Plus 2.7 + @element-plus/icons-vue |
| 状态/路由 | pinia 2 / vue-router 4 |
| 构建 | vite 5;make web-dev(:5173)必须 vite dev——preview 不加载 msw |
| 测试 | vitest(137 用例)+ @vue/test-utils + jsdom;Playwright 1.63(截图矩阵+e2e) |
| 质量 | eslint(max-warnings 0)/ vue-tsc / prettier / verify-layout 脚本(18 项断言) |
| Mock | msw 2.3 浏览器拦截 /api/v1/*(51 端点);VITE_API_MODE=mock|real |
| 包管理 | pnpm workspace(近期切;package-lock 与 pnpm-lock 并存) |
开发环境(docker-compose.dev.yaml,7 中间件)
| 中间件 | 宿主端口 | 说明 |
|---|---|---|
| MySQL 8.0 | 13306 | root/root123,库 gosms;buffer_pool 已调 4G |
| Redis 7 | 16379 | single 模式 |
| Kafka 3.7 KRaft | 19092 | Topic 预创建:make init-topics |
| ETCD 3.5 | 12379 | |
| ClickHouse 24.3 | 18123(HTTP)/19000(Native) | |
| MinIO | 19010/19011(API/Console) | |
| Prometheus+Alertmanager | — | 规则 deploy/monitoring/alert_rules.yml |
网关 dev 固定 :8080(GW_PORT 可覆盖;历史 8081 为当时宿主 8080 被占用的临时覆盖,已废弃,vite proxy 按 8080);Web 测试端口铁律=5173(make web-dev,vite dev;WEB_PORT 不得覆盖、preview/临时容器端口不入口径);外网测试统一入口=https://sms.unimsc.com/(nginx 根路径反代 443→5173+ws Upgrade,vite allowedHosts 已登记;ai.unimsc.com/SmsDev 前缀通道废弃);K8s NodePort 30080/30081(S5 灰度 apply)。
常用命令
# 中间件与初始化
make up && make init-topics && make init-mysql && make init-schema
# 质量门(后端)
make vet && make test # go test -race -cover ./...
make lint # golangci-lint v2.1.6
# 运行
make run # bin/gateway
make run-consumer # bin/consumer
make seed-admin # 首启迁移+超管(密码仅打印一次)
make dev / make dev-stop # 一键全栈(scripts/dev_up.sh 幂等)
make web-dev / web-real / web-test / web-stop
make svc-status # gateway/web/mysql 健康一览
# 集成测试(真实中间件)
go test -tags=integration ./test/integration/...
# K8s(kind)
make ci-local SERVICE=gateway VERSION=dev
环境变量规则
- 前缀
GOSMS_,层级以_连接:mysql.dsn → GOSMS_MYSQL_DSN;切片逗号分隔。 - 高频:
GOSMS_CONFIG/GOSMS_SERVER_HTTP_ADDR/GOSMS_KAFKA_BROKERS/GOSMS_BALANCE_MODE=redis(消费侧必设)/GOSMS_LOG_FILE_PATH(不可写自动降级 stdout)。 - 集成测试:
GOSMS_TEST_REDIS_ADDR/GOSMS_TEST_KAFKA_ADDR/GOSMS_TEST_ETCD_ADDR。
工具链版本
- Go 1.25.0;golangci-lint v2.1.6(
GOTOOLCHAIN=go1.25.0 go install ...@v2.1.6)。 - Node/pnpm(web/node_modules 已就位);字典生成
go run ./tools/gen-dict(npm run gen:dict)。 - kind + kubectl(本地 K8s
go-sms-dev集群,scripts/kind-dev.yaml)。
技术约束
-
重建期代码托管(2026-11-13 修订):内网独立机 Gitea 已上线——
ssh://git@192.168.5.27:24401/Tory/go-sms-V2.git(账号 Tory,公钥=「5.18 SmsDev」;web 经用户侧域名/转发访问)。push 纪律=日终随 bundle 一并 push,本地仓+每日 bundle 备份双轨保留。2026-11-12 原裁决「不装 Gitea」的协作触发条款于 11-13 生效(运营探讨重建计划);网络事实修正:git.smpp.ltd 仅 IPv6 新机不可用、192.168.5.10=New API 网关且不可操作、开发机=192.168.5.18。 -
宿主单块 HDD:写吞吐物理顶 ~55/s(w_await 80ms),压测结论「代码杠杆已用尽,生产换 SSD」。
-
36 表 DDL 幂等(scripts/init_schema.sql);生产 Kafka/Redis Cluster 由运维托管。
-
CI 三套同语义:
.gitlab-ci.yml/.gitea/workflows/ci.yml/make ci-local(当前验收路径)。 -
镜像基线:
go-sms-<service>:dev;CI 用kubectl set image滚动,勿 apply 覆盖运行中镜像标签。
远程开发机(121.46.230.53,2026-11-13 重装后 = 重建主战场)
- SSH:
ssh -p 1822 user@121.46.230.53(公网 1822→VM 内 22 NAT;公钥免密,老机id_ed25519_510已授权实测 SSH_OK);hostname=debian13-smsDev;Debian 13.7 / 内核 6.12.116,纯 CLI。 - 规格:8C(Xeon 8173M,VMware 虚机,宿主为托管实体机)/ 31G 内存 / sda 400G 虚拟盘(ROTA=0):
/92G +/data272G 独立分区(root 所有)。 - S0 评估结论(2026-11-13):① CPUID 无 AVX + VEX 编码执行即 SIGILL(2026-11-13 stress-ng 实测定画像)——dispatch 类软件(glibc/Node/libatomic 类,旧 VM 崩源)免疫(CPUID 干净不选 AVX 路径);但含 VEX/EVEX 编码的二进制执行即崩:stress-ng cpu/stream stressor 0 秒 SIGILL(ILL_ILLOPN@VEX 指令),memcpy(SSE2 实现)正常,git/fio/apt/python 实测全正常。对策:新机编译禁用
-march=native/AVX 选项(Go 工具链无影响,CGO/自编 C 注意);Go 编译循环终验待 Go 安装;② 磁盘实测:顺序写 662MB/s(home dd)+ fio 4K 随机读 76.3k IOPS(312MB/s)/写 25.5k IOPS(QD32·75/25 混合,/data 实测)——HDD 老机 ~100 IOPS 的 500 倍级,消费吞吐/明细回表瓶颈彻底解锁;③ 外网通畅(2026-11-13 二次探测修正):IP 层 ping 223.5.5.5 rtt 4.6ms、TCP 443/53 直连 OK——首测「无外网」为误报(dhcpcd 生成的 resolv.conf 无 nameserver,域名全解析失败);修正动作=dhcpcd.conf 加domain_name_servers=192.168.5.1 223.5.5.5(待 root);DNS 恢复后 apt/Go module/vscode-server 全在线,介质摆渡降为备用通道;④ NTP 未同步(无外网,待 open-vm-tools 宿主对时或 root 处理);⑤ 工具链就位(2026-11-13 apt,阿里云镜像):fio/git/curl ✓,stress-ng SSE2 类 stressor 可用(VEX 类崩,见①),docker 待装;⑥ 归档仓 mirror 落位/data/poc-archive/repos/go-sms.git(S0 闭环后 rebuild-ui=poc-final=5e09a4cc,develop/main/rebuild-ui/poc-final 四 ref 全);⑦ DNS 用户已配(114.114.114.114/8.8.8.8,出网正常);user 已入 sudo 组 + NOPASSWD(sudoers.d/user)已配;评估全程 dmesg 零崩溃。 - S1 工具链就位(2026-11-13):① Docker CE 29.7.2 + compose plugin v5.5.0 + buildx + containerd 2.3.3(aliyun docker-ce trixie 源;Debian 源 docker.io 26 无 compose 插件弃用);
data-root=/data/docker;registry-mirrors=docker.m.daocloud.io + docker.1ms.run(docker hub 直连超时,mirror 实测拉取可用);user 已入 docker 组(重登后免 sudo);json-file 日志轮转 50m×3。② Go 1.25.0=/usr/local/go(aliyun golang 镜像下载,sha2562852af0c…b613校验 ✓);GOPROXY=https://goproxy.cn,direct+GOTOOLCHAIN=local+GOFLAGS=-mod=mod;模块缓存预热 434M。③ gcc 14.2(apt 装;-race 需 CGO,机器无 gcc 时 Go 自动 CGO_ENABLED=0 会直接拒跑)。④ golangci-lint v2.1.6 → ~/go/bin。⑤ 备份 cron=30 3 * * * /usr/local/sbin/backup-v2.sh→/data/backup/v2-YYYY-MM-DD.bundle(保留 14 天,设计规范 §7;首份 v2-2026-11-13.bundle 已落)。 - 新机网络特性留痕(2026-11-13):aliyun CDN(apt https 池与 docker-ce 池)传输偶发中途停滞(TCP ESTABLISHED 但 0 字节,apt 会无限挂死);解法=apt
--print-uris取 URL 清单 → curl--speed-limit 1024 --speed-time 20 --retry 5 -C -熔断续传逐个下 deb →dpkg -i直装。注意:apt 对缓存目录文件名做校验,docker-ce 包名含 epoch(5:29.7.2)而 URL 名不含 → 手放 deb 后--no-download仍会拒;docker-ce deb(URL 名)与 Debian repo deb(URL 名一致)均以 dpkg -i 兜底为稳。goproxy.cn 与 aliyun golang 镜像下载稳定无此象。go.dev / registry-1.docker.io / golang.google.cn(.sha256 路径)直连不可用或超时。 - 连接故障根修三连留痕(2026-11-13,已解决):① root 会话曾把 authorized_keys 权限改成 664(组可写)→ sshd StrictModes 拒绝公钥(表现为:新连接 Permission denied 而旧 ControlMaster 通道存活)——修复
chmod 600;② 老机 ssh config 对该 HostIdentitiesOnly id_ed25519单钥匙 + 对端被换钥匙 = 必败——已补回 inscom2ai-image-deploy 公钥(用户本地 Pd-debian12 钥匙保留共存);③ 老机 ControlMaster(30m 复用)会让会话携带旧的组信息(usermod 后验证 sudo/组必须-o ControlMaster=no -o ControlPath=none绕过或-O exit杀 master)。 - 过桥:bundle(42M)已落位
/data/poc-archive(sha256bfca93fa一致;ssh cat 管道传输——新机无 rsync,链路实测 ~1.5MB/s);归档仓 mirror 已落位 /data/poc-archive/repos/go-sms.git。
重装前历史(2026-11-12 VS Code 排查期,旧 VM,已被重装取代)
- Debian 13 (trixie) / 内核 6.12 / Xfce + xrdp 远程桌面(display :10.0);VS Code 1.146 官方 deb(
/usr/share/code);suer 在 sudo 组。 - 重装计划(2026-11-12 裁决):纯命令行 Debian 13——Xfce/xrdp/VS Code GUI 全弃用(公网攻击面收敛,xrdp 为头号爆破目标);开发形态=本地 VS Code + Remote-SSH,服务器仅 vscode-server(纯 Node,首连自动装,断线自动重连);Cline 扩展装在 server 端。
- 宿主 CPU 指令执行缺陷(2026-11-12 实锤,系统级):Xeon 8173M(Skylake-SP,二手渠道整机特征;2026-11-12 用户澄清=托管机房实体机,非云虚机,微码/宿主不可更换,「报云厂商换宿主/升微码」路径作废),AVX 系全掩/BMI1-2 保留,微码/掩码不一致 → 任意进程可确定性 SIGSEGV/SIGILL(dmesg:code 进程
segfault error 25固定崩点跨 socket 0/4/8/12;extensionHost SIGILL;evolution-alarm 在 libatomic invalid opcode = 非 VS Code 进程同样中招)。在该机排查任何「软件崩溃 bug」前先看sudo dmesg,勿误判为代码问题;根治需云厂商换宿主/升级微码。 - CPU 缺陷对纯 CLI 的影响与缓解(2026-11-12 评估):非零——压测基线可信度>go build/test 偶发假红(项目纯 Go/SSE2 基线,面小)>Node(vscode-server 自动重连兜底)。缓解:①
/etc/environment加GLIBC_TUNABLES=glibc.cpu.hwcaps=-AVX2,-AVX512F,-AVX(glibc 2.41 支持,libatomic/字符串函数回落 SSE2);②重装后开荒第一步=stress-ng(avx2/memcpy/vm)+20 轮编译循环实测复现率,≈0 则接受(「偶发 SEGV 先查 dmesg、重试」入 runbook),频发则建议机房换整机;③压测基线前置 24h 稳定性门槛(dmesg 零新增+进程零重启)。 - VS Code 使用:裸
code(不带 --no-sandbox)可正常打开——冷启动 renderer 闪崩 1 次后自动 reload;--no-sandbox非必需(关沙箱有安全代价)。 - AppArmor:Debian 13 非特权 userns 限制存在,
/etc/apparmor.d/code(vscode, userns, unconfined)profile 正常加载中(2026-11-12 已重载确认)。 - SSH 免交互登录(本机无 sshpass/expect/paramiko):OpenSSH≥8.4 用
SSH_ASKPASS_REQUIRE=force+setsid,或 python3 标准库 pty 驱动(已验证模板);清理远程进程勿用pkill -f(匹配 bash -c 自杀),用pkill -x按进程名。
部署铁律(教训留痕)
- 串行部署:build 完成→kill→确认退出→nohup→
md5sum /proc/PID/exe比对(并行 build+kill 会致旧 inode 进程跑旧代码,Day 70 教训)。 pgrep -f会匹配 bash 壳须排除(watchdog 同款坑)。