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

111 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 技术上下文
## 后端技术栈(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)。
## 常用命令
```bash
# 中间件与初始化
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)。
- **Google Chrome stable 157**(2026-11-15 官方 deb 直装,`google-chrome --version` 验证):AI 登录参考 UI/前端自验的真浏览器通道。**约束(宿主 CPU 缺陷实测)**:Playwright 须 `channel:'chrome'`(自带 chromium newPage 即崩不可用);同一 browser 第 2 个 newPage 必崩(renderer segfault error 25 固定偏移 0x90b1f9 → zombie → newPage 永久挂起),**稳定口径=每会话独立 launch+单 page 内 goto 导航**(fresh 5/5、单页多导航 4/5[失败仅外网网络]实测);固定 args=`--no-sandbox --disable-gpu --disable-dev-shm-usage`。通用会话工具=`scripts/chrome-session.mjs`(带 per-step 超时+FAIL 重 launch,CLI 直跑或 import runSession 改造登录场景)。
- **OCR 工具链(2026-11-15)**:tesseract 5.5 + python3-pil(apt 直装);计算题图片验证码识别方案=`放大4x LANCZOS+Otsu 二值化+psm7/8/6 多数投票`+算式三态解析,脚本模板留档 /tmp/cap-solve.py(环境级工具不入仓,复用时按 activeContext Issue#1 条目重建)。
## 技术约束
- **重建期代码托管(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 同款坑)。