# 构建与测试（长版明细）

## 构建与测试

- **无 libwebp/GCC**：cgo 的 `internal/storage/s3.go` 挡编译 → overlay 换桩
  `dev/s3stub/s3_stub.go`（`-overlay="C:/Users/Tamakyi Gekka/AppData/Local/Temp/tb-webpcheck/overlay.json"`）。
  要检查 s3.go 本身得 tar 复制项目 + `go mod edit -replace`（overlay 换不了 GOMODCACHE）。
- **「编译卡死」= `proxy.golang.org` 不可达**。每条 go 命令前
  `export GOPROXY=https://goproxy.cn,direct GOSUMDB=off GOFLAGS=-mod=mod`（`go env -w` 沙箱失败）。
  1C1G 是正式生产环境，别用「沙箱慢」解释超时。
- DB 测试：`DB_TYPE=postgres DB_USER=postgres DB_PASSWORD=15207786347hXPm DB_HOST=127.0.0.1 DB_PORT=5432`
  （DSN 不带库名，`NewTestDB` 自建临时库后 DROP）。带 DB 的 `go test ./...` 全绿。
- store 方法内用 `NewXStore(db.DB)`，别引用包级单例（测试下 nil panic；`FeatureStateOf` 有守卫）。
- ⚠️ **本沙箱起不了 `TamaBox web`**（session 固定 redis，6379 未开，启动 panic）→ HTTP 端到端只能部署后做。
  探测端口 200 可能是别的进程，必须看日志确认 `Starting web server` 且无 panic。
- ⚠️ **本机 python urllib 不稳定**（代理下偶发读超时，curl 正常）；python 别用 `/tmp`
  （Windows 解析成 `C:\tmp`，与 MSYS 不通）。PIL 在 `~/.workbuddy/binaries/python/envs/default`。
- ⚠️ **验证 Go 二进制里有没有某个中文字符串，不能用 `strings`**：GNU strings 默认只输出
  可打印 ASCII（0x20–0x7E），UTF-8 中文（0xE4+ 开头）整段被丢弃，`strings x | grep 中文`
  恒为 0 —— 曾据此误判「用户没重新编译」，实际二进制是新的。
  正确做法：`grep -ac "中文字符串" 二进制文件`（实测同一个二进制：strings=0、grep -a=1）。
- ⚠️ 替换二进制后**必须重启进程**：`go build -o X` 只改磁盘文件，正在跑的进程仍是旧映像。
  若服务由 systemd/supervisor 管理，再手动 `./X web` 会因端口被占直接退出。
- ⚠️ **分享卡字体不在仓库里**：`static/fonts/` 从未入库也没 embed（`static/fs.go` 的清单里没有），
  `/static/fonts/...` 走 HTTP 是 302 回首页。新环境不手工放字体 → `share-card` 恒 500
  「字体文件未配置或无法加载」。老环境（如生产）能出图只是因为当年手工补过文件。
  排查口诀：响应体是这句中文 → 一定是部署侧缺文件，不是代码回退。
  `getFont` 现已支持 candidates（`font_path` → `static/fonts/*` → 系统 CJK 字体）且不缓存失败，
  补文件后无需重启。
- ⚠️ **`GOSUMDB=off` 会让 toolchain 自动下载失败**：go.mod 要 1.27.3 而 PATH 上的 `go` 是旧版时，
  会报 `golang.org/toolchain@...: verifying module: checksum database disabled by GOSUMDB=off`
  （`go version` 显示的还是 shell 包装器的版本，容易误判成「版本没变」）。
  解法：直接用缓存里的 toolchain 并禁用自动切换——
  `PATH="$HOME/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.27.3.windows-amd64/bin:$PATH" GOTOOLCHAIN=local go test ./...`

## 本地部署（WSL2 Debian，2026-10-27 打通）

用户本机有 WSL2 `Debian`（可 `wsl.exe -d Debian -u root` 免密进 root）。在这上面跑通了完整服务，
从此 HTTP 端到端不必「部署到测试站才能做」。要点：

- **GOROOT 是个坑**：`~/.bashrc` 里 `export GOROOT=/usr/local/go`（1.26.3）。用 `/opt/go/bin/go`
  （1.27.3，从 dl.google.com 下的 tar 解到 /opt）时必须 `env -u GOROOT`，否则
  `compile: version "go1.26.3" does not match go tool version "go1.27.3"`。
  另：GOCACHE 被旧版本编译过也会报同样的错 → 换独立 `GOCACHE=~/.cache/go-build-tb`。
- **依赖**：`apt-get install redis-server python3 python3-requests gcc libwebp-dev pkg-config`
  （有 libwebp 后 `internal/storage/s3.go` 正常编译，不再需要 s3stub overlay）。
  session 与 cache 都硬依赖 redis，6379 不通就起不来；`systemctl start redis-server` 即可（WSL 有 systemd）。
- **库**：DSN 不带库名 → 连的是与用户名同名的库。测试还要 `CREATEDB` 权限（`NewTestDB` 自建临时库）。
  `CREATE ROLE tamabox LOGIN PASSWORD '...' CREATEDB; CREATE DATABASE tamabox OWNER tamabox;
   CREATE DATABASE nekobox OWNER tamabox; CREATE SCHEMA nekobox AUTHORIZATION tamabox;`
- **配置坑**：`data/data.txt` 里的 `[app] title`、`[server] xsrf_expire`、`[captcha] provider`、
  `[rate_limit] *` 全是当前版本不认识的键（启动 WARN 后忽略）。验证码要关外网校验得写
  `[recaptcha] captcha_type = math`。`external_url` 用 http → session cookie 不带 Secure，本地能登录。
- **进程托管**：`/etc/systemd/system/tamabox-test.service`（User=tamakyi、WorkingDirectory=源码目录、
  ExecStart=<二进制> web、日志 append 到文件）。`systemctl restart` 必须 root，普通用户报 Access denied。
- **访问路径**：Windows 侧 `http://127.0.0.1:5877` 被本机别的进程占用（返回 502），要用
  `http://<wsl eth0 ip>:5877`。这个差异正好白送一套 P1-3 的 A/B：
  WSL 内 `curl 127.0.0.1` = 回环对端（模拟 cloudflared 回源），Windows 侧访问 = 非回环对端（模拟公网直连）。
- **抓 IP 伪造**：临时配 `ip_blacklist = 1.2.3.4` + `ip_blacklist_redirect_url`，带头 curl 看有没有 302，
  比读日志直观；配合日志里的 `remote_addr` / `header_ip` 双重取证。
- **限流会绊脚本**：`/api/captcha/generate` 按 IP 限流，批量跑用例会 429，
  `audit.get_captcha` 已加退避重试。SMTP 密码不对只会打日志（`526 Authentication failure`），不影响用例。