# 技术上下文 ## 后端技术栈(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` | **ClickHouse 24.3 交互三坑(S4·D3 真机留痕,clickhouse-go v2 native)**:① `count()` 返回 **UInt64**——Scan `*int64` 报 unsupported,须 `*uint64`(且 Scan 错误不可 `_=` 吞,曾致冷查 total 恒 0);② **无 `DROP PARTITION IF EXISTS`**(24.3 语法不支持)——先查 `system.parts`(database=currentDatabase() AND table=? AND partition=?)存在才 DROP;③ **`?` 绑定 time.Time 有 UTC 化歧义**——时间窗查询参数预格式化墙钟字符串 `"2006-01-02 15:04:05"`(与写入语义同口径)。另:MySQL go-driver `parseTime=True` 下 `DATE()` 结果 Scan 到 `[]string` 会带 RFC3339 尾巴——跨方言日期列举用 `DISTINCT created_at` Scan `[]time.Time` + Go 侧归一化去重;MySQL 8.0 `information_schema.PARTITIONS` 对**非分区表也返回一行 NULL**——已分区判据必须 `PARTITION_NAME IS NOT NULL`。 网关 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-: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 同款坑)。