107 lines
9.4 KiB
Markdown
107 lines
9.4 KiB
Markdown
# 技术上下文
|
|
|
|
## 后端技术栈(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(历史归档规划)、MinIO(文件/号码导入) |
|
|
| 其他 | 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。
|
|
|
|
## 常用命令
|
|
|
|
```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)。
|
|
|
|
## 技术约束
|
|
- **重建期代码托管(2026-11-12 裁决)**:新环境**不装 Gitea**——单人+Remote-SSH 下服务器本地仓即中心(/data/go-sms-v2);备份=定期 `git bundle create --all` 至 /data/backup 并拉回本地;需协作/CI 时再补 Gitea(单二进制+SQLite,5 分钟)。
|
|
|
|
- **宿主单块 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`**(HEAD=9c1ed52d,develop/main/rebuild-ui/poc-final 四 ref 全);⑦ DNS 用户已配(114.114.114.114/8.8.8.8,出网正常);user 已入 sudo 组 + NOPASSWD(sudoers.d/user)已配;评估全程 dmesg 零崩溃。
|
|
- **连接故障根修三连留痕(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 同款坑)。
|