Files
go-sms-V2/memory-bank/techContext.md
T

11 KiB
Raw Blame History

技术上下文

后端技术栈(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 固定 :8081(GW_PORT,8080 被宿主旧进程占用);Web :5173;K8s NodePort 30080/30081。

常用命令

# 中间件与初始化
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 + /data 272G 独立分区(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 镜像下载,sha256 2852af0c…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 对该 Host IdentitiesOnly 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(sha256 bfca93fa 一致;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 同款坑)。