tamakyi/tamabox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: tamakyi/tamabox:main
Branches Tags
tamakyi/tamabox:main
..
compare: tamakyi/tamabox:70b2bcf6441e370756272509d716ff00a9a7674b
Branches Tags
tamakyi/tamabox:main
5 Commits
main .. 70b2bcf644
Author SHA1 Message Date
tamakyi 70b2bcf644 test2 2026-09-08 15:21:51 +08:00
tamakyi 9ddec22f12 test 2026-09-08 15:01:33 +08:00
tamakyi e94c2b57ce 新增：安全告警邮件展示来源 IP 网络归属（CDN/云厂商/WAF） 
- 新增 internal/security/ipinfo：基于 projectdiscovery/cdncheck v1.3.0
  （离线指纹、零外部请求）识别来源 IP 归属，识别失败折叠为展示标签，
  不中断告警链路
- autoban 告警回调注入归属识别；告警邮件新增「网络归属」行，
  命中 CDN/代理网络时提示「封禁可能无法拦截真实来源」
- 新增邮件模板渲染回归测试 internal/mail/mail_alert_test.go
- dev/s3stub：webp(cgo) 本地类型检查桩，替换 s3.go 做全模块编译验证，
  生产 Linux 构建不受影响；dev/overlay.json 指向该桩
- go mod tidy 顺带升级共享依赖（lipgloss/xid/testify 等），
  全模块类型检查与相关包测试通过
 2026-09-08 13:25:20 +08:00
tamakyi 35a846ea40 合并远程更改 2026-09-08 10:16:04 +08:00
tamakyi 2ed27dd55e 0904 2026-09-08 10:10:44 +08:00
378 changed files with 9641 additions and 54219 deletions
Expand all files Collapse all files
.gitignore
+1 -37
View File
@@ -28,40 +28,4 @@ go.work.sum
# otherfile
./workbuddy
./scripts
# 注意：gitignore 不认 "./" 前缀，/outputs 才是「仓库根下的 outputs」。
# outputs 里全是 TestGenPreview / 主题生成器 / 截图这类一次性产物，
# 每次跑都会变，跟版本库无关。
/outputs/
# 蜜罐凭据取证文件：明文账号密码，绝不能进版本库。
# 默认目录由 [security] honeypot_cred_dir 决定（缺省 data/honeypot-creds），
# 若改成别的盘外路径则不受这条影响（那本来也不在仓库里）。
/data/
# 主题生成器的自测脚本是 Python：跑一次就会留 __pycache__，别提交。
__pycache__/
*.pyc
# 本地凭据与一次性状态（测试账号密码等），只留在本机，不进版本库。
# 目录说明见 .workbuddy/local/test-accounts.md 的抬头注释。
/.workbuddy/local/
/.codeartsdoer/
# 本地运行配置与 WSL 测试环境模板：含数据库密码与对象存储密钥，绝不能进版本库。
# dev/wsl-app.ini 的用法见 dev/sync-wsl.sh；同步时必须排除 conf/app.ini，避免被 rsync --delete 删掉。
/conf/app.ini
/dev/wsl-app.ini
/dev/_*.py
# 含真实测试凭据的历史记录与巡检脚本：保留本地文件，但不再纳入版本控制。
/.workbuddy/memory/MEMORY.md
/.workbuddy/memory/topics/build.md
/.workbuddy/memory/topics/sec.md
/.workbuddy/memory/topics/misc.md
/.workbuddy/memory/2026-09-15.md
/.workbuddy/memory/2026-10-19.md
/.workbuddy/memory/2026-10-22.md
/dev/devcheck-e2e.py
/dev/devcheck-avatar.py
/dev/devcheck-image.py
/dev/devcheck-upload.py
./outputs
.workbuddy/memory/2026-09-08.md
-8
View File
@@ -9,11 +9,3 @@
- 教训（重要）：本机 Windows + go1.25.5 下 `-overlay` 行为异常（静默不生效 / "deleted in overlay"），**overlay 不可靠；本地验证用磁盘换桩法**：`cp dev/s3stub/s3_stub.go internal/storage/s3.go`（先备份）→ build/test → 还原。chai2010/webp 是 cgo 库，用户生产编译在 Linux，无需本地真编译。
- `go mod tidy` 顺带升级了部分共享依赖（lipgloss 0.13、xid 1.5、testify 1.11 等），全量构建+测试通过。
- dev/overlay.json 现指向 dev/s3stub/s3_stub.go（旧值指向已删除的 Downloads 副本，已过时）。
## autoban 线上触发实测（box-dev-api.337845818.best，2026-09-08 13:38）
- 基线：/ → 200；敏感路径 → 302（业务跳转，但会计入统计）。
- 60s 窗口内连发 18 个敏感路径：前 ~9 个 302，第 ~10 个起全部 403；封禁后连首页也 403 "403 Forbidden"（中间件先于业务路由，全站拦截）。
- ⚠️ 触发点 ≈ 9~10 次，不是配置的 15：疑似部署侧仍是默认阈值（DefaultThresholdSensitive=10）。需检查服务器 conf/app.ini [security] ban_threshold_sensitive = 15 是否落盘并重启服务。
- 本次触发应已发出一封告警邮件（每 IP 仅一次），可借机验收新的「网络归属」字段。
- 本机出口 IP 已被临时封禁（默认 15 分钟自动解除），期间再测会 403。
.workbuddy/memory/2026-09-10.md
-452
View File
@@ -1,452 +0,0 @@
# 2026-09-10
## 负面情绪提问拦截方案调研（评审，未改代码）
- 盘点提问链路现有 5 道防线，结论：**无任何情绪/意图维度判定**，全部是字面/合规/可用性维度。
- 已验证的代码事实（后续复用）：
- 文本审核走七牛 `POST https://ai.qiniuapi.com/v3/text/censor`，scene=`antispam`，10s 超时（`internal/security/censor/qiniu.go:85`）。
- `IsPass()` 只硬拦 `politics/terrorism/porn`，且 `review` 一律放行 → `abuse`（辱骂）实际漏过（`qiniu.go:55-68`）。
- `censor.go:50-53` 命中 31 天缓存后**重新用 parser 计算 Pass**，缓存不锁死判定 → 收紧 `IsPass()` 无需清缓存。
- 拉黑 `user_block` 只作用于私聊（`route/question/page.go:368` 在 `StartChat` 分支内），**不拦提问**。
- 项目无 at-rest 加密（grep aes/Encrypt 无结果）；无队列/Worker，异步只有 `shared.SafeGo` 裸 goroutine；Redis 仅 session/cache。
- 有内存滑动窗口限流器 `internal/route/ratelimit.go`，可复用做单 IP 限流。
- `conf.Limits.QuestionContentLen` 默认 1000；`AnswerContentLen`/`FollowUpContentLen` 默认 2000（= 七牛文本 2000 字上限的边界）。
## 重要背景更正（用户指出）
- **图片/文本审核服务是七牛云，不是阿里云**。阿里云通道虽仍在 `censor.go` 代码中，但 `conf/app.sample.ini` 的 `aliyun_access_key` 为空，实际不生效。后续所有审核相关评估以七牛为准。
## 七牛云能力（官方文档已验证）
- 文本审核 label 9 类：normal/spam/ad/politics/terrorism/**abuse**/porn/flood/contraband/meaningless；suggestion: block/review/pass + score；≤2000 字；不支持白名单（拉黑词库要提交工单）。
- 七牛自有 LLM（MaaS）：`https://api.qnaigc.com/v1`，兼容 OpenAI `/v1/chat/completions` 与 Anthropic `/v1/messages`，50+ 模型，**用独立 API Key（非 AK/SK）**。
## 产出
- `outputs/llm-moderation-feasibility-2026-09-10.md`：LLM 内容审核方案可行性评审（数据流/失败降级/配置校验/Key 安全/邮件告警/成本限额）。
- 4 个 P0：SSRF（用户自填 API 地址，连通性测试即探测入口）、Key 明文落库、用户 Key 被刷造成损失、失败即发信导致邮件轰炸。
- 核心建议：分层 L1 收紧七牛 `IsPass()`（零成本）→ L2 本地情绪词库 → L3 LLM 只补七牛覆盖不到的语义部分。
- 待用户确认 8 点，最关键：命中后是"提示+仍提交"还是"硬拦"。
## 追加修订（用户实测反馈）
- **用户反馈：七牛对「辱骂」判定过严，正常对话经常误伤** → 撤回原 L1 建议（把 abuse 纳入硬拦），照做会放大误伤。
- 误伤两个真实成因（已代码复核）：
1. 七牛把正常内容判 `abuse` 且 `suggestion=block` → `qiniu.go:55-68` 拒绝 → 提问/私聊直接发不出去；
2. **审核服务不可用时 fail-closed 拒绝**（`page.go:574`、`chat_handler.go:258`）→ 七牛抖动期间全站发不出内容。
- 关键约束：七牛文本审核**不支持白名单**、自定义词库需提交工单 → 无法调准也无法调松，**唯一可控的是"命中后怎么办"**。
- 修订原则：**显式规则硬拦，算法推断只标记**。箱主自定义屏蔽词+高危三类(politics/terrorism/porn)硬拦；abuse/spam/ad/flood/contraband/meaningless 只打标记照常送达；审核不可用改 fail-open+标记待审。
- 落地：questions/messages 加标记列（AutoMigrate 自动加列）+ 后台折叠/筛选 + 设置页「审核严格度」三档（严格/宽松(默认)/仅标记）+ 用 `detail.Score` 自建阈值（默认偏高）。
- 该路线零延迟零外部依赖，顺带消掉 SSRF/Key 明文/Key 被刷/邮件轰炸 4 个 P0。
---
## 「审核严格度」实现（已落地，构建/vet/测试全绿）
**备份（回滚锚点）**：`C:/OtherFiles/Github/TamaBox-v4-mainline-pre-moderation-strictness-20260910.tar.gz`
（git 仓库损坏，用户指示「不要动 git」，改用 tar.gz；304 条目，sha256 `c6cfce2b...`）。回滚 = 解压覆盖回工作目录。
**核心设计：把「是否拦截」从审核服务自身的 Pass 判定中剥离**，新增策略层 `internal/security/censor/policy.go`。
- 档位：`lax`（仅底线）/ `standard`（底线 + abuse≥0.9 + contraband）/ `strict`（底线 + 全部非 normal 维度不限分 + 采信服务 block 建议）。
- 底线 `baselineBlockLabels`：politics / terrorism / porn / **customized**；任何档位无条件拦截、不可关闭（`Decide` 中排第一、无条件 return）。
- 判定顺序固定：底线 → 档位维度（带分数门槛）→ 服务建议（仅 strict）。
- 缺省 `DefaultStrictness = strict`；非法值 `ParseStrictness` 一律回退 strict（保守）。
**⚠️ 重要事实修正（本次发现）**：strict 档 **并非**「与升级前等价」，而是 **⊇ 升级前**。
- 升级前拦截条件 = `!Pass` = (politics|terrorism|porn) 或 服务 suggestion==block（见备份 `route/question/page.go:443`）。
- strict 额外把 abuse/spam/ad/flood/contraband/meaningless/harmful 全部纳入（不限置信度）→ 比升级前更严。
- 已把散落各处「升级不改行为 / 行为等价」的错误注释全部改正（policy.go / moderation.go / conf/static.go / app.sample.ini / db/users.go / i18n 文案）。
- **待用户拍板的取舍**：DefaultStrictness 是否维持 strict。若用户首要诉求是「减少误伤」，应改为 standard（一行常量）；维持 strict 则部署后默认拦截面略扩。
**阿里云兼容（用户本轮要求，已完成）**：
- **rate 量纲 bug（关键）**：阿里云 `rate` 是 0~100，七牛 `score` 是 0~1；不归一化会让 `abuseScoreFloor=0.9` 在阿里云下恒成立、standard 档分级失效。已加 `normalizeAliyunRate()`（>1 则 /100，clamp 0~1）。
- 补映射 `harmful→ForbiddenTypeHarmful`（覆盖用户最初想要的「负面情绪」，仅在 strict 档生效）、`customized→ForbiddenTypeCustomized`（进底线）。
- 未映射 label 不进 `Details`（无法按维度裁决）；`results` 为空时 `ProviderSuggestion=block`（对齐 fail-closed）。
- 结论：**可直接复用，无需改调用方**；只需上述 parser 层归一化/映射，三家通道（七牛/阿里云）共用同一 `Decide`。
**统一入口**：`internal/security/moderation/moderation.go`
- `Check(ctx, strictness, lang, text)` = 调审核 → `censor.Decide` → 返回 err（本地化）。审核不可用仍 fail-closed。
- `StrictnessFor(raw)` = 账号设置优先，空则跟随 `conf.Security.DefaultModerationStrictness`，再回退 strict。
- 三场景入口已全部改走 `moderation.Check`（grep 可复核）：
- 提问/回答：`route/question/page.go:441,574`、`question.go:170`、`follow_up.go:105,164`
- 投票：`route/vote/vote.go:72`、`route/user/vote.go:67,159,1012`
- 私聊：`internal/route/chat/chat_handler.go:259`（用 `pageUser`=箱主，非访客）
**改动文件清单**：
- 新增：`internal/security/censor/policy.go`、`policy_test.go`、`internal/security/moderation/moderation.go`、`route/user/moderation.go`、`templates/user/moderation-strictness.html`
- 修改：`censor/{text,qiniu,aliyun}.go`、`conf/static.go`、`db/users.go`、`form/user.go`、`internal/route/route.go`、`route/question/{page,follow_up,question}.go`、`internal/route/chat/chat_handler.go`、`route/vote/vote.go`、`route/user/vote.go`、`i18n/dict_{zh_cn,zh_tw,en,ja}.go`、`templates/user/profile.html`、`templates/render_test.go`、`conf/app.sample.ini`
- 设置页表单分别挂在 profile 的 提问/私聊/投票 三个面板。
**验证方式（Windows 沙箱无 libwebp/gcc，需 overlay）**：
```
go build -overlay="C:/Users/Tamakyi Gekka/AppData/Local/Temp/tb-webpcheck/overlay.json" ./...
go test -overlay="..." ./internal/security/... ./internal/i18n/... ./templates/... ./route/... ./internal/route/...
```
结果：build 0、`go vet ./...` 0、上述测试全 ok。新增 6 个阿里云/策略用例（normalizeAliyunRate / AliyunParserFeedsPolicy / CustomizedHitsBaseline / NoResultsFailsClosed / UnmappedLabelSkipped）。
注：`internal/db` 测试需真实 DB，环境缺失，与本次改动无关；`censor.go`、`text_test.go` 存在**升级前就有**的空格缩进（gofmt -l 会列出），未动以避噪音。
---
## 第二轮：改动回归审阅（与备份全量 diff 逐项复核）
方法：把备份 tar.gz 解到 `%TEMP%/tb-review/base`，对工作区做 `diff -rq` 拿到精确变更集，再逐项查 bug。
**结论：无 P0（无安全/正确性回归）**。关键安全性质已核实：strict 档拦截条件 **⊇ 升级前**，故默认档下不可能出现「以前拦、现在放」。`censor.Text` 的 31 天缓存命中后**重新走 parser**（`censor.go:50/61`），`Details`/`ProviderSuggestion` 会被重建，不存在「缓存命中导致档位判定失效」。`EnableTextCensor=false` 时 parser 返回 `{Pass:true}` 且 Details 为空 → `Decide` 放行，开发环境不受影响。
### 已修（本轮）
- **🔴 P1 设置页档位回显错误（真实 bug）**：`moderation_strictness` 为空（存量账号，语义=跟随站点默认）时，模板三个 `option` 的 `eq` 全为假 → 浏览器默认选中第一个选项「宽松」，而实际生效是站点默认（通常 strict）。界面显示的档位与真实拦截行为**相反**，直接违背「让用户在切换前就知道会被拦什么」的需求。
- 修法：新增模板函数 `moderationStrictness`（`internal/template/template.go`，内部调 `moderation.StrictnessFor`，与 policy 同源），模板改用 `$current := moderationStrictness $root.LoggedUser.ModerationStrictness` 回显。
- 未用「在 Profile handler 注入 data key」的方案：全仓有 **16 处** `ctx.Success("user/profile")`（各 Update* 校验失败回显路径），漏一处就会让模板读到缺失 key。
- 补 `TestRenderProfileStrictnessReflectsEffectiveTier`（未设置/lax/standard/strict/非法值 5 例）。
- **🟠 P2 `censorVoteForPublish` 档位口径不一致**：同一函数内 `vote.Title` 用 `voteOwnerStrictness(ctx, vote.UserID)`，而 `Description`/选项/字段标签走 `censorCheck`（内部读 `ctx.User`）。当前因 `getOwnedVote` 强校验 `vote.UserID == ctx.User.ID` 而**不可达**（3 个调用路径 678/907/944 都归属校验过），属潜在缺陷。已改为函数开头解析一次 `strictness` 并全程复用。
- **🟠 P2 i18n 字典 diff 污染**：插入新 flash 键时切断了原有对齐组，导致 `admin.flash.deactivated`/`admin.export.errUser`/`admin.export.errQuestion` 三行在 4 个字典里被 gofmt 重新对齐（3 行×4 文件）。已把新键移到该组之后、独立成组，恢复原 3 行。**教训：往 gofmt 对齐组中间插键会把「拆分后的剩余组」重新对齐；应插在组末尾或独立成组。**
- **🟠 P2 死代码**：`TextCensorResponse.ErrorMessage()` 生产与测试**均无引用**（已被 `ErrorMessageFor` 取代），且其「取首个维度」的语义正是本轮要修的错误来源，留着易被误用 → 已删除。`BlockedLabels()` 仅测试使用，但注释声称「供设置页展示」→ 已改为如实描述（UI 目前用 i18n 静态文案）。
### 已核查为非问题（勿重复排查）
- `internal/cmd/censor.go:57,68` 仍直接调 `censor.Text`：这是 `tamabox censor` **回填 CLI**，只写 `content_censor_metadata` 审计字段、不做拦截放行判定，不属三场景提交闸门 → 无需改走 `moderation.Check`。
- 全仓已无「直接判 `resp.Pass` 决定放行」的残留（仅 `db/censor_log.go` 存字段）。
- `LoggedUser` 每个请求都由 `authenticatedUser()` 回源 `db.Users.GetByID`（`internal/context/auth.go:22`），保存后重定向读到的一定是新值，不存在「保存后下拉框还是旧值」。
- `route/user/moderation.go` 用 `ctx.User.ID` 且挂在 `reqUserSignIn` 组内（`internal/route/route.go:374`）→ 越权改他人档位不可行；与 `UpdateHarassment/UpdateBlockWords` 同构（同样无 rateLimit，保持一致）。
### 待用户处理 / 决策
1. **`templates/user/moderation-strictness.html` 被注入 `data-page-node-id` 属性**（全仓仅此文件有，备份/其它 40+ 模板均无 → 非项目约定，疑为页面编辑器标注）。它会**污染生产 HTML**，并让 `render_test.go` 的精确子串断言失败。我未擅自删除（可能属你侧编辑器状态）；但已把断言改为正则 `selectedStrictnessOptions()`，不再耦合属性顺序 → 现在两种情况下测试都稳。**请确认是否要清掉这些属性。**
2. `DefaultStrictness` 维持 strict 还是改 standard（见上一节）：待拍板，一行常量。
3. CHANGELOG 未记入：新功能属用户可见变更，按项目惯例应在 `dev/changelog-source.md` 顶部加条目并跑 `python dev/gen_changelog.py` 重新生成 `static/tamabox.changelogs.json`。**刻意留着等你定了档位口径再写文案**（严格/标准会改变措辞）。
---
## 第三轮：用户三项指示
1. **已删除** `templates/user/moderation-strictness.html` 的 `data-page-node-id` 属性（全仓无任何读取方，纯渲染噪声）。
- ⚠️ **重要机制发现**：**用 Write/Edit 工具写这个文件会被自动重新注入该属性**（且 id 每次是新的一批）；用 **shell（sed）修改则不会被注入**。判断注入方是「文件工具触发的后处理钩子」，不是文件监听。→ **该文件今后一律用 shell 修改**，不要用 Write/Edit。
- 同时把 `render_test.go` 里原本精确匹配 `<option value="standard" selected>` 的断言改成不依赖属性顺序的 `selectedStrictnessOptions()`（正则），这样属性在不在都不会误报。
2. **`DefaultStrictness` 维持 strict**（用户已拍板）。仅更新了 `policy.go` 的注释记录该决定与理由，代码不变。
3. **新增 `[security] text_censor_source`** —— 此前通道链是硬编码的 `[qiniu, aliyun]`，无法选择。
- 取值：`qiniu` / `aliyun` / `auto`（**留空同 auto，即历史行为**：七牛优先、未通过则阿里云二次复核）。
- 常量定义在 `conf`（`CensorSourceAuto/Qiniu/Aliyun`），供 `conf.Init` 校验与 `censor.censorChain()` 共用，避免两处字符串漂移。
- `conf.Init` 启动校验（纯函数 `validateTextCensorSource`，便于单测）：
- 审核关闭 → 不校验；留空/auto → 通过（两者都没凭据时仍不阻断启动，否则 sample 原样拷贝无法启动）；
- 显式选 qiniu/aliyun 但缺凭据 → **启动即报错**（否则运行期审核必然失败，而失败是 fail-closed，会让整站发布/私信不可用且现象隐蔽）；
- 其它取值 → 报错，**不静默回退**（拼错若被当成 auto，运维会误以为已只用七牛）。
- `censor.Text`：循环改为 `for _, censor := range censorChain()`；新增一次性告警 `warnIfNoCensorCredentials`（sync.Once，兜 auto 无凭据的漏网情况，避免按请求刷屏）。
- 顺带把原「HACK: Qiniu's API response is not accurate…」注释改写为如实描述链式复核语义，并说明 qiniu-only 时 `continue` 不会丢判定。
- 文档：`conf/app.sample.ini` 在 `enable_text_censor` 下新增带注释的 `text_censor_source`。
- 测试：新增 `internal/conf/text_censor_source_test.go`（12 例）、`internal/security/censor/censor_source_test.go`（6 例），全绿。
---
## 第四轮：阿里云通道「response data is empty」排查
用户报障日志：
```
ERRO Failed to censor text censor_source=aliyun error="response data is empty"
ERRO Failed to censor text error="no censor source available" strictness=lax
```
（两条同时出现 = 两个通道都没给出结论 → fail-closed 拒签，即整站发布不可用。）
### 根因取证（读 SDK 源码 + 比对官方文档，未凭猜测）
1. 我们的 `aliyun.go` 与**上游 NekoBox `wuhan005/NekoBox` 的 aliyun.go 逐字节一致**，
也与**阿里云官方 Go 示例一致**（`green.CreateTextScanRequest()` + `SetContent(json)`，
`{"scenes":["antispam"],"tasks":[{"content":...}]}`）。→ 请求构造不是本项目引入的问题。
2. 走通了 SDK 调用链，确认「HTTP 2xx + 合法 JSON + `data` 为空」是唯一能产出该错误的组合：
- `sdk/responses/response.go:44` 非 2xx 会被 `Unmarshal` 直接转成 `ServerError` → 走
`errors.Wrap(err, "text scan")`，不会是这条消息；
- `response.go:58` 只有 `AcceptFormat == JSON` 才尝试解析进 `TextScanResponse`（空结构体，必然成功）；
- 我们的 parser 用的是 `resp.GetHttpContentBytes()`，body 非 JSON 会报 `unmarshal response`。
3. 顺带确认真实端点解析正确：`green.EndpointMap` **不含 `cn-shanghai`**，但会一路回落到
`GetEndpointRules` → `green.cn-shanghai.aliyuncs.com`（正确）。
4. 找到一处**确定的代码缺陷**（不是根因，但让根因不可见）：旧 parser 在 `len(Data)==0` 时
只报 `response data is empty`，把顶层 `code` / `msg` / `requestId` 全丢了 → 用户拿不到任何线索。
### 已落地改动（`internal/security/censor/aliyun.go` + `policy_test.go`）
- 抽出 `newTextScanRequest(text)`（便于测试断言请求形态）；**显式 `req.SetContentType(requests.Json)`**。
SDK 的 ROA 默认值是 `application/octet-stream`（`roa_signature_composer.go:88`）。此改动属
**按接口契约对齐**（对已正常工作的环境无副作用），**是否为本例根因未证实**，以下一次日志为准。
- 顶层 `code != 0 && != 200` → 全新分支 `aliyun rejected the request: code=.. msg=.. request_id=.. raw=..`
（与旧「data 为空」同为错误返回，控制流/语义不变）。
- `data` 为空 / JSON 解析失败 / 请求体回显：错误里带上 `code/msg/requestId` 与原始响应摘要
（`aliyunRawDigest`，按字符截断 ≤512，避免切坏多字节）。
- `Censor()` 里 SDK 返回 err 时补 `status` + `body`；`!IsSuccess()` 分支同样带 status/body。
- `data[].code != 200` 仍 fail-closed 置 block（**语义未改**），但在真正决定 fail-closed 的位置补了
一条 Warn（code/msg/taskId/requestId）——否则「审核失败」会伪装成「命中违规」而无迹可循。
- 顺手修掉 `Censor()` 上错误的文档链接（原指向七牛文档 → 改为阿里云 70439）。
- 新增测试：`TestNewTextScanRequestShape`、`TestAliyunRejectedRequestSurfacesCodeAndMsg`、
`TestAliyunEmptyDataErrorCarriesRawResponse`、`TestAliyunInvalidJSONErrorCarriesRawResponse`、
`TestAliyunRawDigestTruncates`。`gofmt`/`go build`(overlay)/`go vet`/`go test ./internal/security/...` 全绿。
### 下一步（等用户）
重新部署后重试一次，新日志会直接显示阿里云返回的 `code/msg/requestId` 与原始响应。
账号侧首要排查项：①内容安全 1.0 是否已开通按量付费；②RAM 子账号是否有 Green 权限；③是否欠费停服；
④如需跨区可在 `getClient()` 写死 `cn-shanghai` 之外调整（该处目前硬编码）。
### 待决策
- 「显式选定通道坏掉 → 整站 fail-closed 不可用」是否要加**启动预检**（启动时发一次探活请求，
失败则告警/拒启）。成本：按条计费 + 启动依赖外部网络；收益：把「静默全站拒签」提前暴露。
### ✅ 根因已确认（同日 15:50，用户回传新日志）
诊断改动生效后一条日志即定案：
```
error="text scan (request body={"scenes":["antispam"],"tasks":[{"content":"测试！"}]}):
aliyun rejected the request: code=596
msg="You have not opened Yundun Content Moderation Service, please go to the page
(https://www.aliyun.com/product/lvwang) to open our service after login Ali cloud console"
request_id=01A08A4B-CCE2-5AAF-9329-A0C51C0F5060
raw={"code":596,"httpStatusCode":200,"msg":"...","success":false}"
```
- **根因 = 阿里云账号未开通「内容安全 1.0」**（账号侧，非代码缺陷）。
- 关键实证：响应体里 `httpStatusCode: 200` + `success: false` + 无 `data` → **阿里云「请求被拒也返回 HTTP 200」**，
所以旧代码只会报「data 为空」这句废话。这一条坐实了第二节的推断。
- **`SetContentType(requests.Json)` 被证伪**，不是根因；保留但已把代码注释改为「接口契约对齐」而非「修 bug」。
- 处置：开通 https://www.aliyun.com/product/lvwang（勾选协议点「立即开通」）；RAM 子账号需 Green 权限；
**开通完成前先切回 `auto`/`qiniu` 恢复线上可用性**。
- 防呆：`conf/app.sample.ini` 的 `text_censor_source` 注释补上「配好凭据 ≠ 可用」+ code=596 的完整说明。
- 报告已更新为确认版：`outputs/aliyun-censor-empty-data-diagnosis-2026-09-10.md`。
- 仍待决策：①启动预检（或折中＝首次账号级拒绝时打一次性带处置指引的告警）；②CHANGELOG 条目。
### ✅✅ 最终根因（同日 16:05，用户开通后仍报 596）
用户按我给的地址开了「AI 安全护栏」，仍报同样的 `code=596`。查证后确认**我上一轮给的地址是错的，且漏了硬门槛**：
| 服务 | 开通前提（官方原文） | 个人认证 |
| --- | --- | --- |
| **内容安全 1.0**（`green` 2018-05-09，本项目在用） | **需账号完成企业认证**（`document_detail/69806.html`，2026-07-23 更新） | ❌ 开不了 |
| 内容安全增强版 2.0（`green-cip` 2022-03-02） | 需完成**实名认证**（`document_detail/477720.html`） | ✅ 可开 |
- 1.0 真正开通入口：`https://common-buy.aliyun.com/?commodityCode=cdi#/open`；
`aliyun.com/product/lvwang` 只是产品介绍页（现为「AI 安全护栏」聚合页），点不出「一键开通」。
- 所以：**个人实名认证账号 + 1.0 API = 596 永久复现**，与 RAM 权限无关
（权限不足返回 403/Forbidden，不是 596；596 是「服务未开通」）。
- 已修正 `conf/app.sample.ini` 的注释（换成正确入口 + 写明企业认证前提 + 三条出路）。
- 报告更新为最终版：`outputs/aliyun-censor-empty-data-diagnosis-2026-09-10.md`（含 A/B/C 三方案对比表）。
- 三条出路：**A** 迁增强版 2.0（个人可开，但要换 `green-cip` + `TextModeration` + 新 SDK，**风险标签体系完全不同，`policy.go` 维度清单需重写**）；
**B** 账号升级企业实名认证（代码零改动）；**C** 放弃阿里云只用七牛（`auto`/`qiniu`，损失「七牛误报二次复核」能力）。
- 已就方向征询用户（AskUserQuestion）。
### ✅✅✅ 已落地：阿里云通道迁移到「内容安全增强版 2.0」
用户通过 AskUserQuestion 选定：**迁移增强版 2.0** + **加一次性告警**（即原「启动预检」的折中方案）。当日完成编码，构建/vet/测试全绿。
**⚠️ 关键事实修正（最容易踩的坑）**：
`green-20220302` SDK 中 `TextModerationResponseBodyData.Labels` 的内联注释列出的标签（10 个，且不含涉政）
**是旧的、不完整的**。以官方《文本审核增强版标签处理建议参考》（`practice_detail/465315`）为准，
2.0 通用服务**包含** `political_content`（涉政）、`violence`（暴恐）、`sexual_content`（色情）、
`C_customized`（自定义词库）→ **底线四件套可完整覆盖，`policy.go` 的 `baselineBlockLabels` 无需放宽**。
**2.0 标签 → ForbiddenType 映射**（`formatAliyunForbiddenType`）：
`political_content`/`regional`→politics（底线）；`violence`→terrorism（底线）；`sexual_content`/`sexuality`→porn（底线）；
`contraband`→contraband；`ad`/`PullinTraffic`/`ad_compliance`→ad；`profanity`→abuse；`religion`→harmful；
`negative_content`/`cyberbullying`→harmful；`nonsense`→meaningless；`spam`→spam；`C_customized`→customized（底线）。
⚠️ 2.0 无「灌水(flood)」维度（同类归入 spam），`ForbiddenTypeFlood` 不再由阿里云产生（七牛仍会返回）。
**其他关键事实**：
- 2.0 通用服务单次 `content` **硬上限 600 字符**；站点内容上限为 提问 1000 / 回答·追问·私聊 2000 /
投票描述 5000 字 → 超长必然超限，故**按 550 字分段、段间重叠 50 字**，标签取并集、风险级别取最高。
- 2.0 **不返回逐标签置信度**，只有整条内容的 `riskLevel` → 折算 high=1 / medium=0.6 / low=0.3，
该响应内所有标签共用同一分值。副作用：`abuseScoreFloor=0.9` 在阿里云下的实际语义变成
「标准档只拦 riskLevel=high 的辱骂」。
- 场景固定 `comment_detection`（公聊评论；官方定位覆盖涉政/涉暴/涉黄底线 + 广告导流）。
- SDK：`alibabacloud-go/green-20220302/v3 v3.5.4`；`openapiutil.Config{RegionId:"cn-shanghai"}` 由 SDK 的
EndpointMap 解析出 `green-cip.cn-shanghai.aliyuncs.com`；`ReadTimeout` / `ConnectTimeout` **单位毫秒**，
直接设在 Config 上即可（不必用 RuntimeOptions）。
- SDK 错误经 `dara.TeaSDKError` 包成 `*dara.SDKError`（有 `GetCode()` 与 `StatusCode` 字段）；
账号级故障用「结构化 code + 消息文本」双重识别（`aliyunIsAccountIssue`）。
- 2.0 开通前提：**仅需实名认证，个人账号可开通**（`document_detail/477720.html`）；
1.0 才是「需企业实名认证」，个人账号 596 永久复现。
**两个设计取舍（容易被后人误删，务必保留）**：
1. 归一化响应带 `api:"TextModeration"` 格式标记，解析器拒绝一切非该格式的载荷；
`censor.go` 阿里云缓存回放解析失败时**退回实时调用**（原来是直接把错误返回上层）。
作用：迁移前 1.0 落库的缓存既不会被误判成「通过」（那会成为绕过审核的后门），
也不会因 fail-closed 让这些历史文本在 31 天缓存过期前一直发不出去。
2. 首次账号级失败（596 / Forbidden / InvalidAccessKeyId …）打**一条**带开通指引的 WARN
（`warnAliyunAccountIssueOnce` + `sync.Once`），之后静默。
**改动文件**：`internal/security/censor/aliyun.go`（整文件重写）、`aliyun_test.go`（新增测试套件）、
`censor.go`（缓存回退）、`text.go` / `policy.go`（注释同步）、`policy_test.go`（删除 1.0 格式旧测试）、
`conf/app.sample.ini` + `internal/conf/static.go`（改为 2.0 开通指引）；
`go mod tidy` 已移除不再引用的 `github.com/aliyun/alibaba-cloud-sdk-go v1.62.26`。
**校验**：`go build -overlay=... ./...` 通过；`go vet ./internal/...` 通过；
`go test ./...` 仅 `internal/db` 失败（信息均为 `Unknown database type: ""`，需真实 PostgreSQL/MySQL，与本改动无关），
其余全绿（含 `internal/security/censor`）。
`gofmt -l` 仅列 `censor.go` / `text_test.go`（改动前既有的空格缩进，按约定未动）。
**报告已更新**：`outputs/aliyun-censor-empty-data-diagnosis-2026-09-10.md` 文首新增「最终落地」章节。
**仍需用户处理**：①到内容安全 2.0 控制台开通「内容审核增强版」按量付费，
RAM 子账号授予 `AliyunYundunGreenWebFullAccess`；②CHANGELOG 条目仍未记入
（`dev/changelog-source.md` + `python dev/gen_changelog.py`）。
---
## 第五轮：私聊审核拦截 UX 修复（用户实测反馈）
用户实测 2.0 功能正常，但发现**私聊页面被审核拦截后「无任何提示 + 输入框内容消失」**。
### 根因（两处）
1. **无提示**：`templates/chat/conversation.html` 没挂 `{{template "base/alert" .}}`，
导致 `SendMessage` 里所有 `SetErrorFlash`（过长/被拉黑/审核拦截…）在这页都渲染不出来。
2. **内容消失**：审核失败走 `SetErrorFlash` + `Redirect`，重渲染的 `ConversationPage`
从不回填 `content`，输入直接清空。
### 改动
- `internal/route/chat/chat_handler.go`：把 `ConversationPage` 拆出共享渲染函数
`renderConversation(ctx, domain, token, prefillContent, modErr)`；`ConversationPage` 改为其薄封装。
私聊审核失败分支由 `SetErrorFlash + Redirect` 改为 `renderConversation(..., content, err)`
——**就地重渲染**：`canSend` 为真时把 `prefillContent` 写入 `ctx.Data["Content"]`，
并把 `modErr` 写成 `ctx.Data["HasError"]/["Error"]`（与提问链路 `ctx.SetError` 同源）。
- `templates/chat/conversation.html`：①加 `{{template "base/alert" .}}`（容器开头）；
②`<textarea>` 内填充 `{{ .Content }}` 回填已输入内容（html/template 自动转义，安全）。
### 验证（Windows 沙箱用 overlay 跑，仅 `internal/db` 因缺真实 DB 失败、与本次无关）
- `go build -overlay=... ./...` 0；`go vet ./internal/...` 0；
- `internal/route`、`internal/template`（模板解析）、`internal/conf` 全 ok；
- **审核严格度仍生效**：`TestDecideBaselineAlwaysBlocks` / `TestDecideByLevel` /
`TestDecideUnknownLevelFallsBackToStrict` / `TestBlockedLabelsIncludesBaselineAtEveryLevel` 全过
（底线四件套任何档位强制拦截、未知档回退 strict，未受 2.0 改动影响）；
- **2.0 迁移未破坏**：`TestAliyunParser*` / `TestExtractAliyunChunkResult` / `TestMergeAliyunChunkResults`
/ `TestAliyunIsAccountIssue*` 全过。
### 备注
- 新增 `base/alert` 后，私聊页**其它** `SetErrorFlash` 提示（过长/被拉黑/每日上限…）现在也会显示；
但那些仍走 Redirect，输入内容仍会丢失。本次只修了用户反馈的审核拦截路径，其余校验失败保留内容属可后续优化项。
---
## 环境事实（用户更正，长期有效）
- **真实运行环境是 Debian**，不要为 Windows 相关问题花时间：本机沙箱才需要 `go build -overlay=...`
绕开 libwebp/gcc（cgo），Debian 生产/开发机 `go build ./...` 原生即可，不需要 overlay。
- 沙箱内若要用 overlay，注意 **overlay.json 的 Replace 键盘符必须小写**（`c:/...`），
大写 `C:/...` 会被 Go 规范化成 `c:\` 后匹配不上、报 `deleted in overlay`；stub 在
`dev/s3stub/s3_stub.go`。本次用 `C:/Users/Tamakyi Gekka/AppData/Local/Temp/tb-overlay2.json` 跑通。
---
## 第六轮：设置面板聚合（新增「防护设置」tab）+ 审核严格度排版修复
用户诉求：① 把防骚扰、屏蔽词、审核严格度、提问密码聚合到 `/user/profile` 下一个独立 tab；
② 审核严格度档位处「一个字就换行」很难看。
### 决策（AskUserQuestion 已确认）
- 新 tab 名称：**防护设置**（i18n 键 `admin.tabSecurity`，tab id `security`）。
- **「页面访问密码」一并迁入**（原先在「用户设置」面板）。
- 旧位置**完全移除，不留跳转提示**。
### 改动
**后端**
- `route/user/features.go`：新增 `ProfileTabSecurity = "security"`，并纳入 `ProfileTab()` 白名单
（不加入的话回跳会落到 account 面板）。
- `route/user/password.go`：`UpdateAskPassword` / `UpdatePagePassword` 的硬编码回跳
（`profileURLWithTab(ProfileTabQuestion)`、`"/user/profile"`）全部改为 `returnTab(ctx)`，
跟随表单携带的 `?tab=`。
**模板**
- `templates/user/profile.html`：tab 栏新增「防护设置」按钮；新增
`<div class="profile-panel" data-profile-panel="security">`，内含 防骚扰 / 屏蔽词 /
审核严格度 / 页面访问密码 / 提问密码 五个表单（action 均带 `?tab=security`）。
提问/私聊/投票面板中这些表单全部删除（**原先屏蔽词与审核严格度被重复渲染 3 份**）。
account 面板移除「页面访问密码」卡（原编号 7 让位，账号操作改为 7）。
JS 面板切换是全泛型（`[data-profile-tab]` / `[data-profile-panel]`），无需改动。
- `templates/user/moderation-strictness.html`（**只用 shell/脚本改，禁用 Write/Edit**）：
1. 档位表格：档位列 `uk-table-shrink` + `white-space:nowrap`、范围列 `uk-table-expand`
—— 修掉右侧长文案把 4 字档位名（畅所欲言/正常水平/不听坏话）挤成逐字折行。
2. 选择区改三行：标题（显式 `display:block`）→ 下拉（独立 div）→
「未设置时跟随站点默认档位。」（独立 div）。
**i18n**：四语字典新增 `admin.tabSecurity`（防护设置 / 防護設置 / Protection / 防護設定），
插在「功能管理」组之后的**独立组**，未切开任何既有对齐组（避免 gofmt 重排污染 diff）。
### 验证
- `go test ./templates/`（含 profile 渲染、严格度回显断言 `selectedStrictnessOptions`）ok；
`./internal/i18n/` ok（四语键一致）。
- `go build` + `go vet` `./route/user/` 均 0。
- ⚠️ **gofmt 提醒（重要，易误判）**：`gofmt -l` 会列出**所有 CRLF 文件**（含本次完全没碰的
`route/user/moderation.go`、`vote.go`），因为 gofmt 把 CRLF 规范成 LF。
剥离 CR 后比对，本次改动**零格式差异** → 格式是对的。
**切勿跑 `gofmt -w`**，那会把文件转成 LF、造成全量 diff 污染。
---
## 第七轮：精简注释（删复述、留 WHY）
用户反馈「注释太多」，要求仅保留重要部分。原则（AskUserQuestion 已确认）：
**保守尺度** —— 删除复述型/装饰型，保留全部安全约束、踩坑、外部服务怪癖，长注释压成 1-3 行。
### 摸底数据（脚本 `comment_survey.py`，排除 outputs/dev/.workbuddy）
- `.go` 139 文件 29,185 行，注释 3,102 行（10.6%）；`.html` 41 文件 7,784 行，注释 152 行（2.0%）。
- 最重：`policy.go` 38.9%、`conf/limits.go` 37.8%、`shared/ip.go` 33.0%、`conf/static.go` 27.8%、
`harassment.go` 25.2%、`aliyun.go` 24.7%（152 行，绝对量最大）、`text.go` 22.2%、`censor.go` 21.3%、
`form.go` 19.8%、`gzip.go` 19.3%、`markdown.go` 18.1%、`route.go` 17.8%（80 行）。
### 第一批已完成（-106 行，-31%）
| 文件 | 原 | 现 | 减 |
|---|---|---|---|
| `policy.go` | 84 | 52 | -32（-38%）|
| `conf/limits.go` | 45 | 25 | -20（-44%）|
| `shared/ip.go` | 58 | 32 | -26（-45%）|
| `aliyun.go` | 152 | 124 | -28（-18%，**仅处理到前 180 行，余下待续**）|
保留的关键信息（勿再删）：fail-closed 语义、严格档 ⊇ 改造前、底线维度不可关、
阿里云 596/600 字上限与分段重叠、格式标记防历史缓存误判「通过」、SDK 标签表不可信、
IPv6 /64 聚合仅限流不可用于黑名单、源站未锁可被伪造头、双 CDN 必须删对方权威头。
### ⚠️ 复用方法（重要）
1. **删注释会触发 gofmt 重排**：删掉字段/映射项之间的注释后，相邻行合并成一个对齐组，
列宽会变。手算列宽易错 → 用脚本 `gofmt_keep_crlf.py <files>`：
**跑 gofmt 后按原文件行尾还原 CRLF**（直接 `gofmt -w` 会把 CRLF 转成 LF，造成全量 diff 污染）。
2. **仓库行尾本就不统一**（`policy.go`/`aliyun.go`/`text.go`/`dict_*`/`profile.html` 是 CRLF；
`limits.go`/`features.go`/`password.go` 是 LF）。改动前先确认，改后保持一致。
3. `grep -c $'\r' file` 在 Git Bash 下**不可靠**（`$'\r'` 可能被当空模式，导致「全部行命中」）。
查行尾要用 Python 数 `b'\r\n'`。
4. `templates/user/moderation-strictness.html` 仍**只能用 shell/脚本改**（Write/Edit 会注入
`data-page-node-id`）。
### 验证
`go build ./internal/security/... ./internal/shared/... ./internal/conf/...` 通过；
`go test ./internal/security/censor/` ok（严格度与 2.0 用例全过，确认删注释未影响行为）。
---
## 续：注释清理第二批 + 编译卡死根因（晚间）
### 第二批已清理（本轮继续）
`conf/static.go`、`conf/conf.go`、`security/censor/{text,censor,aliyun}.go`、`route/{gzip,route}.go`、
`form/form.go`、`template/markdown.go`、`db/{db,feature_control}.go`、`captcha/math.go`、
`route/user/harassment.go`、`route/user/vote.go`（最大，~149→少，N+1→2SQL、sanitizeCSVCell、BOM 等 WHY 保留）、
`db/follow_ups.go`（部分，待构建释放后收尾）、`security/censor/policy.go`（最高比 28%→压缩，保 WHY）、
`i18n/i18n.go`（删内联复述、修 typo）。
### 编译卡死根因（已定位并绕过）
- 真因：`proxy.golang.org` 在本沙箱 `HTTP=000`（连接超时），`go build` 触网即无限等待 → 表象「卡死」。
`goproxy.cn` → 200。解法：`export GOPROXY=https://goproxy.cn,direct GOSUMDB=off GOFLAGS=-mod=mod` + **定向包构建**（勿 `./...`）。
- `go env -w` 失败（`%AppData% is not defined`），无法持久化，只能每条命令 export。
- 重活儿构建（`./route/user/ ./internal/route/ ./internal/db/`，overlay 换 s3 stub 避 cgo/webp）已用上述代理跑通、进行中（1C1G 首编 20+ 分钟）。
### 行尾结论
`core.autocrlf=true` → 工作区 CRLF、blob LF，Git 归一，**无 diff 污染**，不必手动转行尾。
`gofmt_keep_crlf.py` 重建到 `dev/gofmt_keep_crlf.py`（Temp 版被清），保留工作区 CRLF 以免 gofmt -l 误报。
.workbuddy/memory/2026-09-11.md
-42
View File
@@ -1,42 +0,0 @@
# 2026-09-11 工作日志
## 代码审阅（全库，安全/正确性/可优化）
结论：**无 P0、无 P1 可利用漏洞**；仅 P2（一致性 / 健壮性 / 性能）。
### 已验证「没问题」的项（勿重复排查）
1. **越权**：所有写接口均有归属校验 —— `getOwnedVote` 显式比对 `vote.UserID != ctx.User.ID`（vote.go:388-401）；
question 路由挂在 `question.Questioner` 中间件组（route.go:262-274），`PublishAnswer` 二次校验 `question.UserID`；
follow-up 写操作以 `question.ID` 为作用域（`AnswerByID`/`UpdateAnswerByID`）。profile/password/harassment/tags/features 一律用 `ctx.User.ID`。
2. **SQL 注入**：`internal/db` 全部用 `?` 绑定参数；拼接仅出现在常量/配置（dedupeUniqueFields、tagCond、randomFunc）。
3. **XSS**：`internal/template/markdown.go` 白名单消毒扎实 —— strip `on*`、禁 `style`、`safeURL` 协议白名单
（http/https/mailto/相对）、拒 `//` 协议相对、强制 `rel="noopener noreferrer"`。
4. **竞态**：follow-up 用事务 + `FOR UPDATE` 行锁；投票「一人一票」用复合唯一索引。
5. **GORM bool 默认值陷阱**：已规避（`Enabled` 不加 `gorm:"default:true"`，见 feature_control.go:79-81），
且 `reconcileLegacyChatEnabled`（:609-618）修复旧 backfill 脏行。
6. **审核缓存回放无 fail-open**：`AliyunTextCensorParser`（aliyun.go:433-461）与 `QiniuTextCensorParser`
（qiniu.go:133-170）都会从 raw 重建 `Details`，故 `Decide` 仍能按当前档位裁决（改档位对历史缓存同样生效）。
⚠️ text.go:66 注释称「回放缓存结果时为 nil」**是错的**，需修正。
### P2 清单（待用户选批后落地）
| # | 文件:行 | 问题 | 建议 |
|---|---|---|---|
| 1 | censor.go:72,111,118-125 | 缓存按**原文** `text` 查，实际送审 `RemoveTrustedURL(text)`，落库 `Input` 存原文 → 审计与实际送审不一致 + 归一化相同文本重复调 API | 归一化一次，查找/送审/落库统一用归一化文本，原文另存字段 |
| 2 | censor.go:85-102 | qiniu 缓存命中仅 `Pass` 才返回，aliyun 命中即返回（不看 Pass）→ 依赖「aliyun 恒为链尾」隐式前提 | 两分支语义对齐，或显式固化链尾不变量 |
| 3 | text.go:66 | 注释失真（称回放时 Details 为 nil，实际会重建） | 修正注释 |
| 4 | route/vote/vote.go:814-822 | 配额用「插入后计数」判定，非原子条件插入 → 并发可短暂超额（有界、自动结束自愈） | 改 `WHERE count<quota` 条件插入或 DB 计数列 |
| 5 | route/user/profile.go:194-215 | Name/Intro/各 link 无长度校验直传 `db.Users.Update` | 补 rune 长度校验（对齐 vote/block-word） |
| 6 | internal/db/users.go:89 | `User.Email` 带 `json:"email"`（对比 Password/BlockWords 为 `json:"-"`）→ 潜在 PII 泄露 | 改 `json:"-"` |
| 7 | internal/db/db.go:215-222 | 用 `conf.Database.Schema` 拼 `CREATE SEQUENCE`（配置来源，纵深防御） | 校验/白名单 schema 标识符 |
| 8 | text.go:114-141 | `RemoveTrustedURL` 对 12 host × 2 protocol = 24 次整串重建 | 单次正则/一次遍历 |
另：`question.go:214` 提问人 token 在 URL 中（邮件链接），**设计如此**，会出现在邮件日志/Referer，可接受。
### 编译状态（延续 09-10）
- 重包 `./route/user/ ./internal/route/ ./internal/db/` 再次 **30 分钟超时（exit 124，无报错）**
→ 判定为 1C1G 沙箱编译整图慢，**非代码错误**（注释改动不影响编译，20 文件 `gofmt -e` 均可解析）。
- 已确认可编译：GROUP1（security/censor、conf、form、template、shared、captcha）EXIT=0；`./internal/db/` EXIT=0。
- 温缓存重试（task zGnX3L）仍在跑，25 分钟上限。
.workbuddy/memory/2026-09-27.md
-30
View File
@@ -1,30 +0,0 @@
# 2026-09-27 工作日志
## Serverless 迁移可行性评估（只读，未改源码）
用户问：TamaBox-v4 能否像 OpenListTeam/OpenList-Worker 那样改造成 TypeScript + Cloudflare Workers + D1。
**产出**：`outputs/serverless-migration-feasibility-2026-09-27.md`
**结论：技术可行，但工程性价比低——是「整体重写」不是「改造」。**
关键判据（两个项目形态根本不同）：
- OpenList = **无状态文件列表 + 反代**（无会话、无可变状态、存储可降级 map/KV、无图像、无服务端模板）→ 边缘天然匹配。
- TamaBox = **有状态多用户 Web 应用**（Session/CSRF/Redis cache、PG 关系模型、cgo 图像管线、42 个服务端模板）。
标定数据：
- TamaBox：34,664 行 Go（route 7645 / db 6950 / i18n 3689 / security 2675 / internal-route 1653 / template 825）。
- OpenList 原版 9.8MB Go / 24.8k star；OpenList-Worker 21.7MB TS / 416 个 .ts（约 2.6MB 源码）/ 官方团队 / 2025-08-23 立项 → 约一年，且**代码量反超原版**。
P0 硬阻断（11 项）要点：
1. `internal/storage/s3.go` cgo WebP（chai2010/webp）+ `cwebp` 子进程 + `os.CreateTemp` → Workers 无 cgo/无子进程/无磁盘。
2. `route/question/share.go` freetype + `os.ReadFile(font_path)` 渲染中文分享图 → 需整体重写，且 CPU 密集易超 Workers 限额。
3. Session/缓存/限流/自动封禁/去重/统计全在进程内（`internal/cache`、`autoban`、`shared/duplicate.go`、`ratelimit.go`）→ 必须迁 Durable Objects。
4. `internal/route/route.go:386-395` cache 中间件**无条件硬编码 Redis**（不判空配置）。
5. D1=SQLite：无 PG 序列（`db.go:211-234`）、无 `FOR UPDATE`（`follow_ups.go:68`）、无 JSONB（`datatypes.JSON`）。
6. SMTP（`internal/mail/mail.go:129-147`）Workers 禁裸 TCP → 换 HTTP 邮件 API。
7. OTel/Uptrace gRPC 上报不可用。
顺带确认（对后续有用）：`internal/template/minify.go` 当前**未被路由装配使用**（`route.go:99` 用的是 flamego template.EmbedFS），属死代码。`internal/security/ipinfo` 是离线签名、零 DNS。
建议方案：A 不迁移（推荐）；B 只把静态资源+只读接口下沉边缘（EdgeOne/Workers），写路径与图像处理留 Go 源站——项目已有 EdgeOne 回源白名单脚本，该形态已在用；C 完全重写（需 2-3 个月专职 + 功能裁剪，优先 EdgeOne 因其有大陆节点）。
.workbuddy/memory/2026-09-28.md
-13
View File
@@ -1,13 +0,0 @@
# 2026-09-28
本会话的工作实际发生在**另一个仓库** `C:/OtherFiles/Github/rond-with-you`（用户指定的 data 文件夹与该备份都在那边），
TamaBox 仓库这次没动。
- 任务：用真机新导出的 `data/20260928_183908.rondbackup` 在本地测试环境（`conf/app.ini`）实测「rondbackup 合并」。
- 结论：主链路生效（新增 70 地点 / 1 活动 / 134 到访，953 条到访 UUID 全命中、时间零误差，孤儿位移 0）；
查出 3 个问题（重复地点不幂等、到访冲突被活动改名放大且不收敛、21 个长沙地点坐标系差 ~660m）。
- 笔记与报告落在该仓库：`.workbuddy/memory/2026-09-28.md`、`.workbuddy/memory/MEMORY.md`、
`storage/.mergetest/报告-rondbackup合并实测-20260928.md`。
- 随后按用户要求**回档数据库 → 修复前两个问题 → 复测**：改 `internal/rond/diff.go`（`DiffPlaces` 多值索引、
到访活动按 `ZUID_` 身份比）与 `internal/web/backup_diff.go`（多取活动 UUID），共 5 文件 +172/−22。
复测：到访冲突 253→6，地点新增 70→67 且合并后归零，重复合并不再产生重复地点。细节见该仓库记忆。
.workbuddy/memory/2026-09-29.md
-9
View File
@@ -1,9 +0,0 @@
# 2026-09-29
工作仍发生在 `C:/OtherFiles/Github/rond-with-you`（TamaBox 仓库未动）。
- 站长手动合并后追问差异页「地点 X → X」为何算冲突；复现定性：`地点` 比的是**坐标**、页面只印**名称**，
同名不同坐标（连锁店重名 236.8km/8.3km，坐标系 750m）就渲染成看似没变化的一行。
- 顺带发现默认「用实机」已把站内 `中国体育彩票`(src_pk=71) 从贺州搬到佛山（236.8km）；
提出 3 处待修方案（名称兜底加距离上限、地点字段补坐标、mergePlaces 的单槽位映射），等批准。
- 细节见该仓库 `.workbuddy/memory/2026-09-29.md`。
.workbuddy/memory/2026-10-15.md
-226
View File
@@ -1,226 +0,0 @@
# 2026-10-15
## WebP 压缩链路评审（只读，未改代码）
产出：`outputs/webp-compression-review-2026-10-15.md`
### 关键事实（已实证）
- `internal/storage/s3.go:186` 的 `maxWidth=1920` + `Quality:80` 对**所有用途一刀切**；
前端 `profile.html:1390` 头像 cropper 只出 512，服务端却按1920 存 → 头像实测多传 ~7倍。
- `chai2010/webp v1.4.0` 的 `Options` **只有 Lossless/Quality/Exact**；
C 层是裸 `WebPEncodeRGB/RGBA`（`internal/src/webp.c:194-215`）= cwebp method4 默认档。
→ method/sns/filter/alpha_q/near_lossless 全都不可控。实测 method6 再省 3~6%。
- 🔴 **`Dockerfile:16` 用 Alpine apk 但未装 `webp` 包** → 容器内无 `cwebp`
→ `s3.go:201` LookPath 必失败 → GIF 动画 WebP 分支是**死代码**，线上一直原图 GIF，且无日志。
- 🔴 `s3.go:99` / `page.go:707` 用 `image.Decode` **不读 EXIF Orientation**；
`templates/question/item.html:206,238` 的 `accept="image/*"` 是原图直传（无 canvas 归一）
→ 手机竖拍照片转 WebP 后横躺。
- 缺 `len(webp) >= len(orig)` 回退兜底（小图/线框图可能越转越大）。
- `format=="webp"` 会二次有损重编（实测 160KB→140KB，体积收益不确定但画质丢一代）。
- `s3.go` 对同一张图**解码两遍**（99 行取format + 181 行完整解码），4096² 下峰值 ~64MB/张。
- `route/question/page.go:740` PutObject **缺 CacheControl**（`s3.go:158` 有 immutable）。
- `s3.go:187` 只判 `Dx()>1920`，不限制长边 → 竖图 1080×10000（10.8M 像素 < 16.7M 上限）不缩放。
### 实测方法
本机无 libwebp/GCC，Go 侧未编译。体积基线用 Pillow（绑定同一份 libwebp 1.4.0）
对 `outputs/*.png` 真实截图测 m4/m6、q75/80/85、lossless。
`imaging.Lanczos` vs Pillow LANCZOS 的差异未纳入。
**method=6 的编码耗时未实测** —— 这是决定是否采用的关键约束（m6 约为 m4 的 5~10 倍耗时，1C1G 需实测）。
### 方案分批
- 批次 A（低风险）：按用途分档（头像 512/q78、背景 1920/q80、通用 1600/q80）、
加大小回退、webp 透传、限长边、补 CacheControl、GIF 缺 cwebp 补 Warn。
- 批次 B：method=6（需先Dockerfile 装 webp + 实测耗时）、EXIF 归一、统一 GIF 实现、降内存。
---
## 批次 A 已落地（同日）
用户确认**不使用 Docker**（webp 包/cwebp 相关影响可忽略），故批次 A 全部走 Go 侧实现。
### 改动文件
1. `internal/storage/s3.go`（LF）
- 新增导出 `EncodeSpec{MaxSide, Quality}` + 档位 `avatarEncodeSpec(512/78)`、
`backgroundEncodeSpec(1920/80)`、**导出** `GeneralEncodeSpec(1600/80)`
（导出是因为 `route/question/page.go` 要传参给 `ConvertStaticImageToWebP`）。
- `uploadPictureToS3` 新增第 4 参 `spec EncodeSpec`；3 个 Upload* 入口各自传档位。
- `ConvertStaticImageToWebP(r, spec)`：签名变了，用 `imaging.Fit` **同时限宽高**
（原 `Resize(img, maxWidth, 0, ...)` 只限宽，1080×10000 竖图不缩放）。
- 新增 `case "webp"`：已是 WebP 且尺寸合规 → 原样透传，不再二次有损。
- 所有转换分支加 `len(webpData) >= len(原图)` 回退兜底。
- `cwebp` 缺失时 `logrus.Warn`（原先完全静默）；新增 `sirupsen/logrus` 导入。
2. `route/question/page.go`（CRLF，792→794 行）
- 同款 webp 透传 + 体积兜底；用 `image.DecodeConfig` 拿尺寸避免多余全量解码。
- PutObject 补 `CacheControl: public, max-age=31536000, immutable`。
3. `dev/s3stub/s3_stub.go`、`dev/webpstub/webp.go`：桩签名同步。
4. 新增 `internal/storage/encode_spec_test.go`（`fitsWithin` 边界 + 档位值断言）。
### 验证结果（全部实测）
- **编译**：本机无 libwebp/GCC，用**临时副本 + `go mod edit -replace github.com/chai2010/webp=../webpstub`**
让**真实 s3.go** 参与编译（比 `s3stub` overlay 强，后者会把 s3.go 换成桩、等于没检查它）。
`go build ./...` EXIT=0，`go vet ./...` EXIT=0。
- **测试**：`go test ./internal/...`（带 PG）全绿，含 `internal/storage`。
- **兜底逻辑有效性实测**（Pillow，同 libwebp 1.4.0）：
- 头像真实路径（前端 cropper 出 512×512 **PNG**，quality:null 无损）→ WebP 10,486 vs PNG 103,054，用 WebP。
- 线框图 200×200 → WebP 908 vs PNG 652，**回退 PNG**（兜底生效，这就是不加兜底会踩的坑）。
- 纯色 1600×900 → WebP 2,672 vs PNG 6,390，用 WebP。
### 关键坑
- **`go build -overlay` 不能替换 GOMODCACHE 下的文件**（Go 明确报错）。
唯一可行的本机方案是**复制项目到临时目录 + `go mod edit -replace`** 到本地 stub 模块。
- 前端头像 cropper 输出 PNG（`profile.html:1391` `fileType:'image/png', quality:null`），
背景是 jpeg q0.92 —— 服务端转 WebP 的收益主要来自这里。
- 站点模板实际展示尺寸：头像 120px（`.tb-frame-avatar`），背景铺满宽度，
私聊图 `max-width:75%`，提问图 100×100 缩略。→ 头像档 512 有据可依。
### 批次 A 未覆盖
- method 仍锁在 4（`chai2010/webp` 只暴露 Quality/Lossless/Exact）。
- EXIF 方向未处理、GIF 双实现未统一、同一张图仍解码两遍 —— 见下方批次 B。
---
## 批次 B1+B2 已落地（同日，用户批准）
**用户澄清：生产是裸 Linux（不用 Docker），且能确保部署机装了 `cwebp`。**
### 🔴 重要：原报告的 method=6 结论被实测推翻
原报告写「m6 耗时是 m4 的 5~10 倍」——**未实测，错的**。实测（取中位数、颠倒顺序防干扰）：
| 场景 | m4 | m6 | 倍数 | 体积差 |
|---|---|---|---|---|
| 1600x4830 (7.7MP) | 1867ms | 2229ms | 1.2x | -2.9% |
| 1920x1080 背景 | 464ms | 655ms | 1.4x | -3.3% |
| 1200x800 配图 | 253ms | 492ms | 1.9x | -3.0% |
| 512x512 头像 | 60ms | 81ms | 1.4x | -3.5% |
**结论：代价远小于预估，但收益只有 3%——1.2~1.9x CPU 换 3% 不划算，决定不做 method=6。**
（另注：Pillow 绑的是 libwebp 1.6.0，项目是 1.4.0，耗时数值仅供相对比较。）
### B1 EXIF 方向归一
- 新增 `internal/storage/exif.go`：`jpegOrientation`（手工解析 APP1/Exif + TIFF IFD0，
**不引新依赖**，项目原本无 EXIF 库）、`applyJPEGOrientation`（走 `orientedImage` +
`draw.Draw` 一次性拷贝，支持全部 8 种方向）。
- 接入 `ConvertStaticImageToWebP`，**顺序必须是「先归一方向，再限边缩放」**——
归一会交换宽高，顺序反了会按错误的边长做缩放判断。
- 为何不可事后修：**实测转码成 WebP 后 EXIF 被整体丢弃**（字节流无 `Exif` 标记），
方向信息永久消失。且 `image.Decode` 与 Pillow 默认都不读 EXIF，已实证。
### B2 GIF 统一
- `convertGifToAnimatedWebP` 导出为 `ConvertGifToAnimatedWebP`，`page.go` 的 GIF 分支
改为复用同一实现（此前 `page.go` 完全跳过转换）。
- 新增 `maxGIFFrames = 200` + `gifFrameCount`（遍历数据块统计 Image Descriptor，
**不解码像素**，常数级开销）。`CheckPixelLimit` 只看 GIF 逻辑屏尺寸，
500 帧 2000x2000 的 GIF 体积小但会让 cwebp 长时间吃 CPU。
- cwebp 参数补 `-metadata none`。
- 两处 GIF 分支都加 `len(webp) >= len(原图)` 兜底。
### 验证
- `go build ./...` EXIT=0、`go vet ./...` EXIT=0、
`go test ./internal/... ./route/...`（带 PG）**全绿**。
- 新增测试 `exif_test.go`（JPEG 手工构造 APP1 段，覆盖大小端/越界/截断/非 JPEG；
8 种方向逐像素校验）、`gif_test.go`（1/12/200/201 帧 + 垃圾输入）。
### 踩坑记录（都是我自己写错的）
1. **`gifFrameCount` 恒返回 0**：漏跳 7 字节 Logical Screen Descriptor，
`pos` 停在 LSD 首字节（宽度低位）→ 首轮命中 `default` 返回 0。
LSD 的 packed 在 `data[10]`（=pos+4），**必须无条件 pos += 7 再按 flag 加色表**。
2. **`buildJPEGWithOrientation` panic**：`entry[10:12]` 只有 2 字节却调 `PutUint32`。
IFD 条目固定 12 字节，next-IFD 偏移占最后 2 字节，保持 0 即可。
3. **`image.Config` 没有 `Dx()/Dy()`**，是 `Width`/`Height` 字段。
4. **`color.RGBA().RGBA()` 返回 alpha 预乘值**，不能简单和 `v<<8` 比较，
要四个通道一起比。
5. **WebP 桩不产出字节** → 依赖真实编码器的端到端断言在本机无法成立，
已改为 `t.Skip`（桩环境跳过），像素级映射由单测覆盖。
---
## 部署后线上验证（用户已部署 box-dev-api）
新增 `dev/devcheck-avatar.py`（头像链路，可复跑）。**A 分档线上确认生效**：
上传 1600x1600 JPEG（124,941 B）→ 存储为 **512x512 WebP, 1,496 B**。
### 🔴 线上验证暴露的真实缺口（待修）
**EXIF 归一的位置太晚，比例校验看不到归一后的方向。**
- `s3.go:110` `asp.check()` 只用 `image.DecodeConfig` 拿宽高，**不读 EXIF**；
- EXIF 归一在 `ConvertStaticImageToWebP` 内部（第 240+ 行），**晚于比例校验**。
- 后果：手机竖拍照片（像素 4032x3024 + Orientation=6，实际显示 3024x4032）
直传头像会被判「比例不符 1:1（偏差 0.333）」而拒绝——**尽管用户看到的是方形**。
实测线上确实如此：传 1536x512+EXIF=6 被拒，头像 URL 未变。
- 前端走 cropper（canvas 会归一方向）不受影响，故只影响**绕过前端的直传**。
- 修法方向：`asp.check` 先读 `jpegOrientation`，对 5/6/7/8 交换宽高再比比例。
别为一次校验就完整解码（大图内存），只做 EXIF 段解析 + 宽高交换即可。
### 验证脚本踩坑
- 提问成功页**不渲染图片**（`templates/question/success.html` 无图片区），
图片只在 `question.go:50` 的**详情页**渲染；且提问图 key **不带 `picture/` 前缀**
（是 `<年>/<月>/<纳秒>.<ext>`），头像才带 `picture/`。→ 断言正则要分开写。
- `/user/profile/update` 是完整资料表单，`UpdateProfile` 有 12+ 个 `required` 字段
（`internal/form/user.go:7`）。只发 `_csrf` 会被挡在 Bind 阶段、头像根本不上传。
做法：从 profile 页**抓取所有 input/select/textarea 的 name=value 回填**。
- 头像上传成功是 **302**，头像 URL 在跳转后的页面里（不是响应体）。
## 补完 B1 + B3（2026-10-15 夜）
### B1 补完：EXIF 比例校验缺口
- `aspect.check` 签名改为 `(cfg image.Config, orientation int) error`——**不再自己DecodeConfig**，
由调用方传入已解析的宽高，顺带消除一次重复的文件头读取。
- 内部：`orientationSwapsDimensions(orientation)` 为真（5/6/7/8）则交换 w/h 再比比例。
- `imagecheck` 新增 `CheckAspectRatioSize(w, h, wantW, wantH, tol)`；
`CheckAspectRatio(r,...)` 改为薄封装（内部走 DecodeConfig + 调Size 版），行为不变。
- `exif.go` 抽出 `orientationSwapsDimensions`，`applyJPEGOrientation` 里的 switch 改为调它（去重）。
### B3：合并重复解码（峰值内存减半）
- 根因：`uploadPictureToS3` 里 `image.Decode` 为拿 format 解一遍 → `ConvertStaticImageToWebP` 内再解一遍。
- 改法：`image.DecodeConfig` 一次同时拿 **format + 宽高**（不解像素），
供「像素上限校验 / 比例校验 / WebP 透传判断」三处共用；完整解码只发生在真正要转码时。
- `ConvertStaticImageToWebP` 签名 `(io.Reader, spec)` → `([]byte, spec)`：
调用方手里已有原始字节，不必再包一层 `bytes.Reader`（也不必内部 `io.ReadAll` 复制）。
内部随之删掉重复的 `CheckPixelLimit`（调用方已在解码前校验过）。
- `route/question/page.go` 同步：删掉 `image.Decode`取 format 与 `DecodeConfig`取 cfg 的两次调用，
改为一次 `DecodeConfig`；新增本地 `fitsWithinSide(cfg, maxSide)`。
- `dev/s3stub/s3_stub.go` 同步签名（去掉 `io` import）。
- **实测堆峰值增量**（runtime.MemStats，含保留引用强制不回收）：
| 输入 | 一次解码 | 两次解码 |
|---|---|---|
| JPEG 4000×3000 (2.3MB) | 18.1 MB | 36.1 MB |
| PNG 3000×3000 (33KB) | 36.1 MB | 72.1 MB |
→ 正好 2 倍。1C1G 上并发上传大图时这是决定性的。
## 线上验证通过（2026-10-16 上午）
脚本：`dev/devcheck-upload.py`（**取代 `dev/devcheck-avatar.py`**），12/12 全通过。
### ⚠️ 重要纠正：头像路径测不出 EXIF 比例校验缺口
头像要求 **1:1 是对称比例** —— EXIF 归一（5/6/7/8 交换宽高）后比例**不变**。
所以修没修缺口，头像路径表现完全一样。之前 `devcheck-avatar.py` 那个
「1536x512 + ori6」用例**根本测不到点上**（3:1 和 1:3 都不是 1:1，两边都会被拒）。
**能触发缺口的是背景 16:9（非对称）**。
### 核心用例（背景 16:9 + EXIF Orientation=6）
像素 1080x1920（竖，比例 0.5625）+ ori6 → 肉眼看到 1920x1080（16:9）
- 修复前：按像素判比例，偏差 |0.5625 - 1.7778| = 1.215 >> 0.01 → **被误拒**
- 修复后：先交换宽高，偏差 0 → 放行
### 线上实测数据
| 用例 | 输入 | 存盘结果 |
|---|---|---|
| A 分档头像 | 1600×1600 JPEG 125,865 B | webp (512,512) **1,542 B** |
| 背景正向对照 | 1920×1080 JPEG 93,484 B | webp (1920,1080) 7,582 B |
| **背景 EXIF ori6** | 1080×1920 JPEG 138,842 B | webp (1920,1080) 9,900 B |
| 反向用例 | 1080×1920 无 EXIF | **被 16:9 校验拒绝** ✅ 未把校验放宽 |
### 像素级方向验证（尺寸对≠ 方向对）
与 **Pillow `ImageOps.exif_transpose` 作黄金标准**比「红色标记条包围盒」：
```
黄金标准(Pillow exif_transpose) 红条bbox=(0, 0, 1916, 88) -> 顶部
线上存盘(本项目 WebP) 红条bbox=(0, 0, 1916, 88) -> 顶部
```
**完全一致** → 方向归一正确。这条已固化进脚本（`redness_bbox()` + 一条断言）。
### 踩坑
- 用「上下左右取平均亮度」判断红条位置**不可靠**：采样带（H//10=108px）比红条本身
（w//12=90px）还宽，红色被稀释成背景色 → 误判「方向未归一」。
正确做法是**按颜色阈值 r>150&&g<90&&b<90 定位像素包围盒**。
- 排查时**必须先建立黄金标准**再判定「我实现错了」，否则会去改本来正确的代码。
.workbuddy/memory/2026-10-18.md
-461
View File
@@ -1,461 +0,0 @@
# 2026-10-18
## 运营侧内容治理：饭圈黑话拉踩/挂人问题（诊断 + 方向）
用户观察到部分箱主页面出现拉踩、黑话辱骂、挑动群体对立（样例 `/_/52mxtx1314`，85 条问答，
内容为「避雷/壁垒/挂人 + 圈内代称」，如咸菜坤/县城坤/猪肝/澄毒/忘羡姐/端水洁癖/蟹脚coser）。
### 已核实的事实（代码侧）
- `moderation.Check` 已覆盖提问入口（`route/question/page.go:441`）、回答、私聊、投票、追问；七牛只硬拦
politics/terrorism/porn，`review` 一律放行 → **通用审核对黑话零命中**，样例文本无一个传统脏字。
- 箱主自建屏蔽词上限：`conf.Limits.MaxBlockWords=10`、`MaxBlockWordLen=10`（`internal/conf/limits.go`），
对「一人一个代称」的场景容量不匹配。
- **全站无举报入口**：`grep Report` 无结果；处置能力只有箱主侧 Delete / SetPrivate / SetPublic。
- 现有成本控制：30 次/分钟限流、数学验证码、同 IP+同内容重复拦截（`shared.DuplicateGuard`）、
`harassment_setting` 的 register_only 档。`autoban` 只针对后台路径扫描，不涉及内容行为。
- `Question.FromIP` 已落库但**未被任何运营/聚合逻辑消费**。
- 单题页/提问箱页已全局 noindex（`internal/context/context.go:243` 的非公开页分支）→ SEO 不是主要传播面，
扩散主要靠截图外传。
### 关键判断
根因是**激励结构**而非审核强度：匿名零身份 + 提问进后台默认不公开 + 箱主逐条回答后公开（样例中连「？」这类
单字回答也算）+ 页面可分享。攻击者收益是「被朗读、被围观」，不是「发出去」。因此加词库/调最严档
投入产出极低且放大误伤。方向按三层：结构层降低收益（已回答≠自动公开、含第三方指涉的投稿默认私密）、
成本层用行为信号（来源配额、同 token 聚合）替代词库、处置层补举报-下架-按来源封禁并留痕。
本次仅给方向，未改代码。下一步待用户选定：出具体变更清单，或先落「举报 + 批量处置」最小闭环。
## 追加：箱主主动引导投稿（处罚口径讨论）
用户澄清：本例是**箱主引导用户投稿挂人**，不是被动受害；提议"禁用提问 N 天，多次累计直接封号"。
### 新核实的事实
- **单题分享卡是公开的一键外传通道**：`QuestionShareCard`（`route/question/share.go:792`）只要
`answer != "" && !IsPrivate && question.UserID == user.ID` 就渲染整张卡片（含箱主头像/背景/水印/二维码），
路由 `GET /_/{domain}/{questionID}/share-card` 在公开的 `Questioner` 分组内。挂人内容因此可以变成无痕图片流出站外。
- **首页/探索分发无任何信誉门槛**：`users.show_in_home` 由箱主自选，`GetShowInHome` / `GetByTag` /
`getRandomUsers` 只按 created_at 或随机排序，不查举报/处置记录。高互动挂人箱可直接获得平台曝光。
- **per-user 功能开关已存在**：`feature_controls`（user_id + feature + enabled + 时间窗 + quota），
`FeatureOpen` / `FeatureStateOf` 是唯一判断点 → 但它是**箱主自设**，`Save` 由本人调用，
若复用为处罚，箱主可自行 `enabled=true` 解除，语义也混淆。处罚需独立 "平台限制" 层，优先级高于用户设置。
- `User` 模型无任何限制/处罚字段；现有只有 Deactivate（自停用）、BanUserAndCleanup（物理删）、restore。
- 「公开可见 = 已回答」（`Questioner` 已挡私密/未回答），所以**「回答」这个动作同时是生产与公开**，处罚打这里最准。
### 立场（待用户确认）
- 赞同罚箱主：主动引导投稿属滥用产品组织围攻，不是内容治理能覆盖的。
- 反对罚「提问（收信）」：伤害来自「发布」，禁收信对已公开的 85 条无效，且给箱主"被平台打压"叙事。
正确梯子是从传播面往下收：停止分发 → 收窄公开 → 冻结发布（回答/公开）→ 停用页面 → 封禁。
- 反对「多次被禁自动封号」：本场景举报本身是攻击武器，自动级联等于给组织化举报装自动扳机。
必须"举报成立（带证据快照）+ 人工判定 + 可申诉 + 留痕"。
- 判据必须用行为指纹而非文本关键词：挂人内容占比、独立指涉对象数、处置后复发率。
- ⚠️ 本例箱主自述被"澄毒长期辱骂"，可能是互殴一方 → 流程必须双向取证，否则单边处罚会激化对立。
## 追加：改为运营者人工裁定（用户倾向）
用户提出：被举报不自动封号，交由运营者本人判断。此方向认可，但补三条前提，否则会退化成"看心情处置"：
1. 判定标准必须**先书面化**（什么算挂人：可识别第三方 + 贬损/号召规避/曝光主页 + 无公共利益），
否则同一人不同时间判出不同结果，比误封更伤公信力。
2. **证据包自动生成**（内容快照 + 来源 IP 聚合 + 该箱主历史处置 + 同 token 的关联条目），
人工只做裁决，不做取证的体力活。
3. 处置必须**留痕 + 可申诉 + 有冷静期**（举报后 24h 再判），这是平台履行"通知-删除"义务的自证材料；
自动封号反而更难自证。
分级矩阵（裁定 × 内容性质）作为处置口径：不成立→不处理（C 类转人工）；成立首次→A 提示整改、
B L1 停止分发、C L1+L2；成立复发→A L1、B L2、C L3；恶意持续→A L2、B L3、C L4→L5。
互殴/选边风险：无法判定过错方时**对等处置**（双方同 L1），不选边；运营者本人有圈内立场，
封号类必须二次复核 + 统一模板公告，不写个人评价。L1 类建议静默生效（不单独通知），
避免暴露"平台在盯内容"后转为图片/缩写等更隐蔽表达。
运营侧还缺一个"处置台"：举报列表、证据聚合、一键执行 L1–L5、留痕查询 —— 目前完全没有。
## 追加：用户明确要求「不要后台」，改为无 UI 实现
审阅后确认项目结构：`/user` 是箱主自助面板（`reqUserSignIn`），**无 admin 角色、无站方后台**；
CLI 骨架在 `cmd/tamabox.go`（`internal/cmd/*.go` 每个命令一个文件，范式见 `ban.go`：`conf.Init` → 拼 DSN →
`db.Init` → 操作 → 确认 → 执行）。告警可用 `conf.Security.SecurityAlertEmail`（`internal/conf/static.go:70`，
autoban 已在用）+ `mail.SendSecurityAlertMail`。
因此"处置台"改为三条非 UI 腿：
1. **举报采集**：单题页举报按钮 → `content_reports` 表；对箱主可见走 `/user/questions?filter=reported`
（这是他自己的收件箱，不是站方后台），举报的处置第一责任人仍是箱主。
2. **告警**：达到阈值（同一箱主 24h 内 N 条举报）发邮件到 `security_alert_email`，这是运营者唯一需要的"入口"。
3. **处置**：`TamaBox reports --domain` 出证据包、`TamaBox restrict --domain --level --days --reason`、
`TamaBox unrestrict`。状态写 `user_restrictions`（带 `expires_at`，判断时比较时间 → **过期自动失效，不需要 cron**）。
生效点（已定位）：`QuestionShareCard`（share.go:808）、`GetShowInHome`/`GetByTag`/`getRandomUsers`
（users.go:620/643/749，注意 GetRandom 有 30s 缓存）、`FeatureOpen`（feature_control.go:364，可一处覆盖箱主自设）、
`PublishAnswer`/`SetPublic`/`AnswerFollowUp`、`question.Pager`（L4 整页停用）。
关键约束（已向用户说明）：不能复用 `feature_controls`（箱主可自行 `enabled=true` 解除，语义混淆）；
不用配置文件方案（要重启、无法表达到期时间）；无后台 ⇒ 只能**事后处置**，不能事前审核，口径需写成
"发布后 24–48h 内可被处置"；举报必须防刷（同 IP + 同 question 唯一），否则邮箱会被刷爆。
## 已落地（第 1–2 步 + L1 两个出口），已实测
备份：`C:/OtherFiles/Github/TamaBox-v4-mainline-before-abuse-restrict-20261018.tar.gz`（3.2M，排除 .git/.workbuddy）。
新增/改动：
- `internal/db/restriction.go`（新）：`RestrictionLevel` L1–L4、`UserRestriction`、`ContentReport`、
`RestrictionsStore`（Create 替换语义 / RevokeActive / ActiveLevel / ActiveLevels / ListByUserID）。
两个模型都**刻意不嵌 dbutil.Model**：处置记录与举报都不软删（撤销走 `revoked_at`），
且带 `DeletedAt` 的唯一索引会留下"删了仍占槽位"的陷阱。
- `internal/cmd/restrict.go`（新）：`reports` / `restrict` / `unrestrict`，复用 `fmtScan` 做 YES 确认。
- `internal/db/db.go`：`AllTables` 加两表，`db.Init` 装配 `Restrictions`。
- `tamabox.go` + `cmd/tamabox.go`：注册三个命令（并给根入口补上一直缺失的 `restore`）。
- `route/question/share.go`：`QuestionShareCard` 在任何级别处置下都拒绝生成分享图（fail-closed）。**L1 核心出口**。
- `internal/db/users.go`（CRLF，用 python 脚本改）：`GetShowInHome` / `GetByTag` / `getRandomUsers`
加 `id NOT IN (activeRestrictionsSubQuery(...))`，把被处置箱主从首页/探索/标签/随机位摘除。
`GetRandom` 有 30s 缓存 → 随机位最多滞后 30s，其余即时。
- `internal/db/restriction_test.go`（新）：覆盖替换 / 升级 / 到期失效 / 撤销幂等 / 曝光排除。**测试全绿**（3.87s）。
实测踩到的两个坑：
1. **只改 `cmd/tamabox.go` 命令不生效** —— 真正入口是根 `tamabox.go`，报 `No help topic for 'reports'`。
2. 证据包比例首版写成「举报次数 / 公开回答数」，实测出现 **166.7%**（5 次举报 / 3 条回答）。
已改为「被举报**条目数** / 公开回答数」，举报次数单独展示。
CLI 冒烟（临时 PG 库 + 临时 ini）：reports 证据包 → restrict L1 → 证据包显示生效 → pending 列表 →
unrestrict → 显示"已撤销"；升级 L1→L3 后旧记录 `revoked_at` 置位、新记录 L3 生效。清理已 DROP 临时库。
未做（下一步）：L2/L3 发布侧拦截（`PublishAnswer`/`SetPublic`/`AnswerFollowUp` + `FeatureOpen` 覆盖箱主自设）、
L4 整页停用、举报按钮与箱主面板筛选、邮件告警。分享卡拦截未做 web 端到端验证（仅编译 + 单测覆盖 store 层）。
## 已落地（第二批：L2 / L3 / L4 发布侧），编译与单测通过，web e2e 受沙箱限制未做
- `internal/db/restriction.go`：加 `restrictionLevelRank` + `RestrictionAtLeast(level, target)`。
显式权重而非字符串比较（将来加 L10 不会静默排错）。空/未知级别恒 false，防止脏数据锁死箱主。
- `route/question/question.go`（CRLF，python 改）：
- `PublishAnswer`：L3+ 拒绝（`question.errRestrictedPublish`）；L2 **先 SetPrivate 再 AnswerByID**，
保证任何时刻都不出现「公开 + 已作答」的中间态（不是先答后藏）。
- `SetPublic`：L2+ 拒绝（`question.errRestrictedPublic`），否则等于箱主自行解除处置。
- `route/question/follow_up.go`：`AnswerFollowUp` L2+ 拒绝 —— 追问回答同样是公开内容且没有私密档可降。
- `route/question/page.go`：`Pager` 里 L4 → `Redirect("/restricted")`。此处 **fail-open**
（DB 出错放行）：它不承担外传通道职责，fail-closed 会让所有箱子一起白屏。
- `route/user/restriction.go`（新）+ `templates/user/restricted.html`（新）+ `internal/route/route.go`
注册公开路由 `/restricted`（必须在 reqUserSignIn 之外）。
- i18n 4 语言各加 5 键（`question.errRestricted*` / `question.flash.answeredPrivate` / `restricted.*`），
`TestDictionaryComplete` 通过。i18n 与 route 文件均为 CRLF：用 python 插行 → `gofmt | 转 CRLF` 写回。
修正上一轮的判断：**`FeatureOpen` 不需要改**。L3 的语义是「冻结发布、仍可收信」，而 feature_controls 控制的是
收集（收信）；关掉它反而违背 L3 定义。L4 已经由 Pager 整页挡住。
验证：`go build ./...` EXIT=0；`TestRestrictions` / `TestRestrictionLevelValidation` / `TestRestrictionAtLeast`
/ `TestDictionaryComplete` 全绿。**L4 与分享卡的 HTTP 行为未验证** —— 本沙箱无 redis，
`TamaBox web` 启动即 panic，详见 MEMORY.md 的构建与测试一节。
## 追加：部署自检脚本（用户要部署到测试服务器）
新增 `dev/devcheck-restrict.sh`：串起「基线 → 施加 L4（断言 302 + /restricted 200 + 文案）→ 降级 L1
（断言页面 200 + 分享卡 302）→ 撤销」，默认 dry-run，`RUN=1` 才执行，`trap EXIT` 兜底撤销。
只依赖 CLI 与 curl，不需要 psql。`bash -n` 通过，LF 行尾。
同时核实：`Dockerfile` 的构建命令是 `go build ... ./cmd/`（不是根目录），所以两个入口必须同步 ——
已写进 MEMORY.md。部署前必须先确认 `./NekoBox --help` 里有 `restrict`，否则是旧产物。
手册里另注明两项只能人工手测：L2（回答应保存为私密）、L3（回答应被拒绝）。
### 首次实跑反馈（用户 dry-run）
用户给 `DOMAIN=admin56` 跑 dry-run，结果 2 项 FAIL。日志证据：`SELECT * FROM "users" WHERE domain='admin56'`
→ **record not found**，说明该 domain 不存在（很可能把账号名当成了 domain）。所有 `/_/admin56` 的 302
都来自 `GetByDomain` 失败后的 `Redirect("/")`，与处置无关 → **L4 那项 PASS 是假阳性**。
同时 dry-run 不施加处置，前后状态没变，状态断言本来就无意义 —— 是脚本设计缺陷。
已修 `dev/devcheck-restrict.sh`：
1. 基线不是 200 直接中止并打印排查建议（302 常见原因 + 查真实 domain 的命令）；
2. dry-run 在基线后短路，不再做状态断言（只验命令存在、基线、停用页）；
3. 新增 1b「停用页是否部署」+ 文案断言，dry-run 也能验 i18n/模板。
教训（已与既有坑同类）：**302 / 200 都不能单独证明处置生效**，必须先确立「基线 200」这个前提。
### 二次实跑：7/7 全绿（真实环境）
`DOMAIN=admin6`：基线 200 → L4 302 → L1 200 + 分享卡 302（qid=73）→ 撤销后 200。
证明 L1 分享卡拦截、L4 整页停用、撤销、以及 L4→L1 的**替换语义**在真实库上都按预期工作。
**随后发现并修掉一个顺序缺陷（L2）**：原实现把「强制私密」放在 `moderation.Check` 之前，
一旦审核失败（内容违规或审核源不可用，fail-closed），题目已被改成私密——箱主一次失败的编辑
会让原有公开内容凭空消失。现已移到审核通过之后、`AnswerByID` 之前，仍满足
「任何时刻不出现公开+已作答」（此刻它是未作答的私密题）。编译 EXIT=0、gofmt 干净。
⚠️ 该修复需重新部署才可在测试站手测 L2/L3。
L2/L3 的手测断言（比看 flash 可靠）：
- L2 后 `select is_private, answer from questions where id=<qid>` → `t` 且 answer 非空，公开页不显示；
- L3 后 `answer` 仍为空串（未被写入），`is_read` 不变。
- 干扰项：回答会走七牛审核，审核不可用会 fail-closed 报「审核服务不可用」，那不是处置问题。
### L2 线上实测：功能生效，但「箱主无感知」被误判成没效果
用户报「L2 没效果」。我用匿名视角实测（这是我能独立做的部分）：
- 公开页 `/_/admin6` 只出现 73，**不含 88**；
- 匿名访问 `/_/admin6/88` → **302 到首页**；对比 `/_/admin6/73` → 200。
结论：L2 私下里是生效的。用户误判的两个原因：
1. 他**以箱主身份**看单题页 —— 箱主本来就能看自己的私密内容，页面当然「一切正常」；
2. **我的 bug**：`question.flash.answeredPrivate` 只写进了 4 个 i18n 字典，**代码里从未使用**，
成功后仍提示「回答发布成功」。已修：L2 分支改用 `forcedPrivate` 布尔切换 flash 文案。
教训：这些 i18n 键写完必须 grep 调用点；「加了文案」不等于「接上了逻辑」。
### 用测试账号自测（已跑通登录态全链路，不需要用户点击）
用户提供测试箱主 `admin6`（密码不落盘）。用 python + urllib 跑通：
`GET /login` 取 `_csrf` → `GET /api/captcha/generate` 取 `{id, question}`（形如 `5 × 5 =`，
注意乘号是 `×` 不是 `*`）→ 算答案后提交 `g-recaptcha-response="<id>:<答案>"` → 登录成功；
再 `GET /_/admin6` 取表单 csrf → `POST /_/admin6`（字段 `content`）发提问 →
`POST /_/admin6/{id}/answer`（字段 `answer`）。
实测结论（qid=89）：
- **L2 服务端生效**：回答保存成功，但该题变私密 —— 匿名访问 302 到首页，公开页只有 73；
- **flash 仍是旧文案**「回答发布成功」→ 服务器跑的是 21:22 部署的二进制，我 21:45 的 flash 修复未部署。
- 88（用户手测）与 89（我自检）都是测试数据，均已被 L2 强制转私密，测完需在后台清理或保持私密。
### L3 验证（重新部署 + 切 L3 后）
qid=90：发提问成功（L3 允许收信 ✔）；`POST /answer` **没有重定向**、URL 停在 `/answer`、
重新加载单题页仍有回答表单 → **发布确实被拒绝、内容未写入**。
但响应里**没有任何提示文案**（`uk-alert` 只出现在 CSS 里）→ 又一个 bug：
⚠️ **同请求渲染不能用 `SetErrorFlash`**。`ctx.Success("question/item")` 是直接出页面（没有 302），
而 `SetErrorFlash` 写的是 session、要等下一次请求才读 → 提示静默消失，箱主看到的是「点了没反应」。
已把 3 处（PublishAnswer L3 / SetPublic L2 / AnswerFollowUp L2）改成 `ctx.SetError(...)`，
并顺手修了 `follow_up.go` 里同类的 moderation 失败分支（既有缺陷）。编译 EXIT=0。
**该修复需再部署一次**；部署后当前仍是 L3，可直接验提示是否出现。
### 重新部署后 L3 提示验证：通过
qid=90 再答一次：`ALERT: 当前处于平台处置期，已暂停发布回答` 已渲染；仍无重定向、回答表单仍在
（未写入）。L3 全链路闭环。待办：用户要求后续做「`SetErrorFlash + Success` 全量清理」专项。
剩余未验：L2 的「已保存为私密」提示（需把 admin6 切到 L2 后自测），以及举报采集链（未开始）。
### L2 提示验证：通过（qid=90）
```
post url: /_/admin6/90 （正常 302 回题目页）
ALERT: 已保存为私密：当前处于平台处置期，回答不会公开
匿名访问 90 -> 首页；公开页 ids: [73]
```
L1/L2/L3/L4 至此全部有真实环境实测证据：
- L1：页面 200 + 分享卡 302（qid=73）
- L2：回答成功 + 转私密 + 匿名不可见 + 专用提示
- L3：回答被拒（无重定向、表单仍在、未写入）+ 拒绝提示
- L4：整页 302 → /restricted 200 + 四语言文案
测试数据：88（用户手测）、89（L2 自检）、90（L3/L2 自检，现已答且私密），均需在测试站清理。
admin6 当前处于 L2（到期次日），必要时 `unrestrict` 解除。
## 举报采集链（已落地，编译 + 单测 + 模板检查通过，未部署验证）
新增/改动：
- `internal/db/report.go`（新）：`ReportsStore` —— `Create`（唯一索引冲突静默为幂等成功）、
`QuestionIDsByUser`（箱主列表标标，排除已删除提问）、`CountByUserSince`（告警阈值）。
理由枚举 `harassment/doxxing/divisive/other` + `IsValidReportReason`。
- `internal/form/question.go`：`ReportQuestion{Reason}`（`valid:"required;maxlen:32"`）。
- `route/question/report.go`（新）：`Report` handler。**不要求登录**（目击者是匿名访客）；
理由白名单；同 IP 同题幂等且提示与首次一致（避免变成内容存在性探测接口）；只写库不改可见性。
- `route/question/abuse_notify.go`（新）：阈值告警 24h≥8 或 7d≥20，24h 冷却（进程内 map + mutex），
复用 `conf.Security.SecurityAlertEmail`，`shared.SafeGo` 异步发送。**只提醒不自动处置**。
- `internal/mail/mail.go` + `templates/mail/abuse-alert.html`：`SendAbuseAlertMail`。
邮件只给计数与下一步命令，**不贴举报内容原文**（邮件会被转发归档，等于又复制一份挂人内容）。
- `internal/route/route.go`：`POST /_/{domain}/{questionID}/report`，`rateLimitMiddleware(10, 1*time.Minute)`。
- `templates/question/item.html`：回答下方 `⚑ 举报这条内容`，`<details>` 折叠 + 固定理由下拉，
仅 `{{ if not .CanDelete }}`（非箱主）可见。
- `templates/user/question-list.html` + `route/user/question.go`：箱主列表加「被举报 N 次」红色 badge，
**只给数量不给举报人 IP**。
- i18n 4 语言共 11 个新键（report.* / qlist.reported*）。
验证：`go build ./...` EXIT=0；`TestReports` PASS（首次写入 / 同 IP 幂等 / 异 IP 计数 /
时间窗口 / 驳回后不计入）；`TestDictionaryComplete` PASS；`go run ./dev/checktpl` → all templates syntax OK
（项目自带模板语法检查工具，改模板后必跑）。
未做：箱主列表的「只看被举报」筛选（目前只有 badge）；举报驳回/成立的处置动作（目前 status 只有 pending）。
### 举报链线上验证：4/4 通过
- 入口：单题页 `/73` 出现「举报这条内容」+ form action `/_/admin6/73/report`；
- 首次举报：POST 302 → flash「已收到举报，感谢反馈」；
- 同 IP 重复：同样 302 + 同样文案，无失败提示（幂等）；
- 箱主 `/user/questions`：出现「被举报 **1** 次」（多次重复提交后计数仍为 1，反证幂等生效）。
**过程教训**：中途 python urllib 报「读超时 25s」，一度怀疑服务端挂起。实测 curl 同一接口
1.6~1.7s 正常返回 302，`location=/_/admin6/73`，手动 GET 也 200。真因是 python 走本地代理
（`https_proxy=127.0.0.1:54881`）偶发挂起 + `/tmp` 路径在 Windows python 与 MSYS 之间不互通。
已写进 MEMORY.md：**验证线上行为优先用 curl**。
### 告警触发验证（进行中）
直接 SQL INSERT 不会触发告警（`notifyAbuseIfNeeded` 只在 HTTP 举报 `created=true` 时调用）。
正确姿势：SQL 补到 7 条 → 删掉自己那条旧记录 → 再用 HTTP 提交一次，使 count 恰好到 8。
已按此执行（curl 提交返回 302 + 「已收到举报」），等待确认日志
`Abuse alert mail sent` / `Failed to send abuse alert mail` / 什么都没有（= `security_alert_email` 为空）。
### 邮件告警验证通过
配置 `security_alert_email` + 重启后，补到 7 条再 HTTP 提交第 8 条，邮件成功收到；测试数据已清理。
举报链至此全部闭环。
### 静默丢失专项清理（用户要求的那项）
静态扫描 `route/**/*.go`：flash 调用后第一个 `Success(`/`Redirect(` 判定，共 **9 处**缺陷
（`follow_up.go` 2、`page.go` 1、`question.go` 1、`profile.go` 5），全部改为
`SetError(err[, f])` / `SetInternalError()`。`Set*Flash + Redirect` 112 处正常，未动；
`vote.go:702/704` 是扫描误报（其后 switch 之后才是 Redirect）。
`go build ./...` EXIT=0；`go test ./internal/db/ ./internal/i18n/` 全绿（36s）。
⚠️ 这 9 处只做了编译与静态验证，未逐条构造触发条件（需传超大图/失效追问 id），
部署后实际遇到对应错误时观察提示是否可见。
### 举报加验证码 + 箱主列表「只看被举报」筛选
- 举报验证码：`form.ReportQuestion` 加 `Recaptcha`（**刻意不加 valid:required**，空值交给
`captcha.Verify` 判定，否则 Bind 失败会被统一提示成「请选择一个举报理由」）；
`Report` handler 签名加 `recaptcha recaptcha.RecaptchaV3`，调 `captcha.Verify`（与提问/私聊同源）。
模板按 `CaptchaType == "math"` 双分支：math 用隐藏域 + `.math-captcha-trigger`（header 的全局弹窗
用 `btn.closest('form')` 定位表单、`form.querySelector('[name="g-recaptcha-response"]')` 回填，
**不依赖 id**，所以举报表单可直接复用）；非 math 用 `.g-recaptcha` + 自定义 callback `tbReportCaptchaOk`。
- 筛选：`/user/questions?reported=reported`，复用已查出的 `reportCounts` 在内存过滤，
新增 `SelectedReported` + 模板第 5 个下拉（reportFilter / reportedOnly）+ 4 语言文案。
验证：`go build ./...` EXIT=0；`go run ./dev/checktpl` → all templates syntax OK；
`go test ./internal/i18n/` 通过。**未部署**，且加了验证码之后原来的 curl 测试方式要改成先算题再提交。
### 部署后验证：4/4 通过
- 无验证码提交 → 302、**未写库**、提示「验证码不能为空」（i18n key `captcha.errEmpty`，非硬编码）；
- 带正确算数验证码 → 302 + 「已收到举报，感谢反馈」；
- 同 IP 重复（换新验证码）→ 同样成功提示（幂等，未新增记录）；
- 筛选：全部页 `73, 88, 89, 90`，`?reported=reported` 只剩 `73`，下拉 `option value="reported" selected`。
测试遗留：73 号题有 1 条举报（我的测试），需 `DELETE FROM content_reports WHERE question_id = 73;` 清理。
## 新增 `TamaBox hide-public`（存量批量处置）
`internal/cmd/hide_public.go` + 两个入口注册。默认只动「公开且已回答」的题；
`--only-reported` 只处理有 pending 举报的（推荐）；`--since N` 限时间窗。
编译 EXIT=0，gofmt 干净。**未在服务器验证**（需部署）。
## 待办与建议（已告知用户，按优先级）
- P0 举报状态闭环：箱主删除/设私密后，该题 pending 举报应置 `accepted`，否则告警阈值会被已处理的旧举报
不断推高（狼来了），且无法统计「成立率」。当前 status 永远停留在 pending。
- P0 箱主侧处置可见性：`/user/questions` 顶部常驻条幅（读 restrictions），避免像今天这样 L2 生效但箱主不知情。
- P1 箱主侧举报通知（某条 ≥3 次时告知箱主自查）、`reports --stats` 全站视图（发现恶意刷举报）。
- P2 社区规则页 `/rules`，处置时引用条款。
- 明确不建议：举报数达标自动处置（武器化）、箱主申诉后台（违背无后台约束）。
## 建议落地（P0/P1/P2 全部完成，编译 + 单测 + 模板检查通过，未部署）
- **P0 举报闭环**：`ReportsStore.MarkAcceptedByQuestion`，在箱主 `Delete` / `SetPrivate` 成功后调用
（失败只记日志，不回滚用户操作）；`hide-public` CLI 批量后同样标记。新增 `reportPendingTTL = 30d`：
`QuestionIDsByUser` / `CountByUserSince` / `CountByQuestion` 都按时间窗过滤，**超期 pending 视为过期**，
用查询过滤而不是定时任务（无后台项目不需要调度器）。
- **P0 处置期条幅**：`/user/questions` 顶部读 `Restrictions.ActiveLevel` 渲染常驻 warning
（`qlist.restrictionBanner`，四语言，带级别与到期日）。解决「L2 生效但箱主不知情」。
- **P1 箱主自查提醒**：单条内容待处理举报**恰好等于 3** 时给箱主发邮件
（`mail/question-reported.html`），用「恰好等于」避免每条举报都发；箱主 `Notify=none` 时不发。
邮件明确写「不代表平台已判定违规」。
- **P1 `reports --stats`**：全站 Top 被举报箱主 + Top 举报 IP，用于识别「举报被武器化」。
- **P2 `/rules` 社区规则页**：公开页 + `templates/rules.html` + 四语言 10 个键。
内容含「明确禁止的 4 类」「处置梯度 5 级」「被举报怎么办」「被攻击怎么办」，是处置的引用依据。
⚠️ 文案由我起草，**需用户过目**（尤其对外承诺的措辞）。
验证：`go build ./...` EXIT=0；`checktpl` OK；`TestReports`/`TestRestrictions` 全绿。
### 部署后验证：3 项通过，1 项 500 待查
- ✅ 处置期条幅：登录 admin6 的 `/user/questions` 出现「限制期」文案（1 处）；
- ✅ 举报 badge：「被举报 1 次」；
- ✅ 闭环：`POST /set-private` → badge 归 0、公开页不再出现 73；
`set-public` 返回 200（不是 302）是**预期** —— L2 禁止设公开，不是 bug。73 现处于私密，需先 `unrestrict` 才能恢复。
- ❌ **`/rules` 返回 500**（其余公开页 `/`、`/about-me`、`/sponsor`、`/deactivated` 均 200）。
已在本地排除：模板语法 checktpl 通过、i18n 四语言键齐全（grep 确认在 map 内）、`t` 函数返回 string 不抛错。
**待用户提供服务端日志**（500 只回 22 字节 "Internal Server Error"，无细节）。
顺带修掉一个**我引入的回归**：`templates/render_test.go` 的 `mockItem` 缺 `ReportCount`，
导致 `user/question-list` 渲染测试失败（`can't evaluate field ReportCount in type interface {}`）。
已补字段；同时把 `{{ if gt .ReportCount 0 }}` 改为 `{{ if .ReportCount }}`（更宽容，零值即假）。
`go test ./templates/` 恢复全绿。
### /rules 500 根因：模板没进 embed 清单
日志：`template: rendering error="html/template: \"rules\" is undefined"`。
**`templates/embed.go` 是显式文件清单**（并非我原先以为的整目录 embed）。新增的顶层
`rules.html` 没写进 `//go:embed ...` 那行 → 没被打包 → `ctx.Success("rules")` 找不到模板 → 500。
编译、checktpl、单测全部无感（测试不渲染该页），只有实际访问才炸。
已把 `rules.html` 加进清单，编译 EXIT=0、`go test ./templates/` 通过。
⚠️ 以后新增**顶层**模板必须改 embed 指令；子目录下的文件已被目录项覆盖。
MEMORY.md 里那条错误认知已纠正。
### /rules 修复后验证：四语言全通过
`rules=200`（39KB）；标题依次为「社区规则与内容边界 / 社群規則與內容界線 /
Community rules and content boundaries / コミュニティルールとコンテンツの境界」；
处置梯度段落存在。
发现规则页**没有任何入口**（页脚原本全是外链，无站内链接），已加
`<a href="/rules">` 到 `templates/base/footer.html` + `site.footer.rules`（四语言）。
编译 EXIT=0、checktpl OK、i18n 与 templates 测试全绿。**需再部署一次生效**。
补充（用户要求）：处置条幅里「如有疑问请通过页脚找站长联系」后面再挂一个 `/rules` 链接，
用 `·` 分隔（`qlist.restrictionRulesLink`，四语言）。模板压成单行避免多余空白。
编译 EXIT=0、checktpl OK。仍需部署。
## 规则页扩展 + 注册强制同意（用户要求）
- **规则分两类**（关键设计）：`rules.forbidden` 重写为
「一、严重违规（直接删内容 + 按情节封禁，**不适用分级**）」6 条（涉政/暴恐/色情涉未成年/违禁品赌博诈骗/侵害未成年人/隐私），
「二、社区冲突（**按影响面分级**）」4 条（挂人、辱骂、群体对立、垃圾广告）。
`rules.enforce` 相应说明「分级只适用于社区冲突；严重违规不走分级，涉法配合有关部门」。
四语言同步。这样避免「挂人只停分发、涉政也停分发」的错误预期。
- **注册强制同意**：`form.Register` 加 `AgreeRules string`（`form:"agree_rules" valid:"required"`,
msg `form.register.agreeRules`）；注册页在 language 之后加 checkbox + `/rules` 链接（`target="_blank" rel="noopener"`）。
**服务端校验是必须的**：前端 required 可绕过，而这个勾选是「用户已知悉规则」的唯一凭证。
- 顺带同步 `dev/devcheck-e2e.py` 的三处注册 POST，加 `"agree_rules": "1"`，否则 e2e 注册步骤会全部失败。
验证：`go build ./...` EXIT=0；checktpl OK；i18n 与 templates 测试全绿。
未用 modal 而用新标签页：规则正文很长，iframe 弹窗体验差且要重复维护内容。
### 部署后验证（规则扩展 + 注册同意）：全通过
- `/rules`：含「严重违规」（6 条底线条目 + 涉政表述）、「社区冲突」（4 条）；
- 四语言标题正确；
- `/register` 有 `agree_rules` 勾选框 + `/rules` 链接；
- **不勾选直接 POST 被服务端拦下**（提示走站点默认语言 ja：
`コミュニティルールをお読みのうえ同意してください`），且**未创建账号**（`/_/tbprobe` 仍 302）；
- 页脚与处置条幅里的「查看社区规则」链接都在。
### UI 微调（已改，未部署）
- `rules.html` 底部「返回首页」容器加 `uk-text-center`（原先左对齐）。
- `question/success.html` 两个按钮改为 flex 等宽：`flex: 1 1 160px; max-width: 220px`，
容器 `uk-flex uk-flex-center uk-flex-wrap`。**用 flex 均分而不是固定宽度** —— 各语言文案长短差异大，
等宽不能靠文字长度。纯布局改动，不涉及 i18n，四语言自动一致。
补充：验证码弹窗「验证并提交 / 取消」两个按钮也不等长，按用户要求把 `captcha.submit` 改短：
提交 / 送出 / Submit / 送信（该键只被这个弹窗使用）。
⚠️ 用户反馈「成功页按钮还是老样子」时，先确认**是否真的部署了**：直接抓线上 HTML 看有没有新标记
（`grep 'uk-margin-large-top uk-text-center'` 在 `/rules` 上）。实测那次线上仍是 `uk-margin-large-top"`
旧结构 → 与浏览器缓存无关，是代码没更新。以后别先怀疑缓存。
（第二次复测已生效：`uk-text-center` 在、弹窗按钮 `>送信<`、成功页 `flex: 1 1 160px` 出现 2 次。）
## 受控用户强制最高审核档（用户要求：不分级，全部级别）
- `moderation.EffectiveStrictness(ctx, userID, raw)`：**有任何处置（L1–L4）就返回 strict**，忽略账号设置。
**处置查询失败时回退账号自身设置**，而不是"失败即强制 strict" —— 否则 DB 抖动会让全站突然加严、
正常提交被大面积误拒，影响面远大于漏放一个受控账号。
- 7 个审核调用点全部从 `StrictnessFor(raw)` 改为 `EffectiveStrictness(...)`：chat_handler、follow_up×2、
page、question、user/vote×3、vote/vote。`StrictnessFor` 保留为纯解析函数（模板回显用）。
- `UpdateModerationStrictness`：处置期内直接拒绝保存并 flash `admin.flash.strictnessLocked`。
- 设置页 `templates/user/moderation-strictness.html`：`$root.StrictnessLocked` 时提示 + select/按钮 disabled。
⚠️ 该文件仍只能用 shell/python 改（Edit/Write 会注入 `data-page-node-id`），本次用 python 精确替换。
- Profile handler 注入 `StrictnessLocked`（读 ActiveLevel）。
验证：`go build ./...` EXIT=0；checktpl OK；db/i18n/templates 测试全绿。
性能：每次内容提交多一次 `user_restrictions` 查询（走 user_id 索引），审核本身要走七牛网络，1ms 可忽略。
.workbuddy/memory/2026-10-20.md
-290
View File
@@ -1,290 +0,0 @@
# 2026-10-20
## 01:10 shiroko 主题补「空气层」
- 用户问「还有没有其他元素，贴合主题又不突兀」。结论：场景压白 38% 后整页亮度只有 235~246，
再摆物件（书包/粉笔/纸飞机）一定会像贴纸，所以走**纯渐变造光**路线。
- 做了 4 个候选截图（A 纯窗光 / B 白散景 / C 光环符号 / D 组合），用户选 D。
⚠️ **B 是反面教材**：白色散景叠在已经压白的场景上，实测差异 0.14 级，肉眼完全不可见。
要"提亮"必须先有暗部，真正起作用的是「底部压深 + 暖色光斑」的组合。
- 最终 `--tb-deco` 后 4 槽：左窗光柱（112deg）、右侧 120px 暖散景（88% 30%）、
脚下 560×170 地面光斑（28% 94%）、底部 24% 压深。亮度差 3~9 级。
- 验证手段（本轮**模型读不了图**，全靠数值）：留白区差分（与候选 D 差 0.0）、
分区亮度表、横向扫描相邻像素差 max 4（判色阶断层）、PNG 体积比对。
- ⚠️ 造预览页两个坑：① 覆盖块必须包在 `<style>` 里，裸写会被当正文渲染，整页布局炸掉；
② `--tb-deco` 各层之间**漏逗号**会让整条声明失效 → 人物和所有背景层全没，且各变体看起来"完全一样"。
以后先 diff 两个变体的 CSS 文本再截图。
- `StaticVersion` → `20261020a`；提交 `fb94b8c` 已推送。文档 `docs/theme-shiroko.md` 加「空气层」一节。
## 08:30 重画光环
- 用户反馈「光环变形太奇怪，而且中间没有扣干净」。根因两条：
① AI 画的环本身歪（bbox 291,93–584,232，比头还宽、偏移到左边）；
② 环内是**封闭白孔**（面积 5190px 的包围区域），四角 floodfill 进不去 → 抠完环里糊着一团白。
- 做法：非白像素从环上一点漫水拿到独立连通域（与头发不连通，头部顶端在 y≈265，环只到 232），
整块抹白；**先把 alpha 建好，再在 RGBA 上画新环**——环心天然就是透明的，不用给封闭孔补洞。
- 新环参数：中心 (515,160)、100×34、线宽 10、-7° 倾斜、4 倍超采样后 LANCZOS 缩小、
外加 45% 模糊柔光；颜色 (127,211,220)，压白 16% 后实测环心 (164,220,224)。
- 坑：擦除矩形右边界要绕开**灰色狼耳**（x>630，y 190-260，颜色 (139,140,146) 不是青色），
差点一起抹掉。判据是连通域 bbox 而不是"上方全是空白"。
- 验证：alpha 字符图确认环闭合、环心 alpha=0；渲染后页面里青色像素 bbox (201,467)-(271,649)，
环在 y 468-486，头顶约 505，间距正常。
- `StaticVersion` → `20261020b`，图片 `?v=20261020b`；提交 `2e9bd6b` 已推送。
## 09:40 部署反馈三修 + 自行车/步枪
- **狼耳顶端被削平**：上一版用矩形 `(281,83)-(594,242)` 抹旧光环，右下角正好切到左耳尖
（耳尖在 y≈185、x 420-480）。改成只抹光环的**非白连通域**（bbox 291,93-584,232，与头发不连通）。
- **手内侧 / 大腿内侧白没抠干净**：那是**闭合**的白色区域，四角 floodfill 进不去。
加封闭白孔检测（>=246 且不与边缘连通、面积>=40）整块掏成透明。
⚠️ 阈值必须 >=251 才能当"背景"：背景恒为 (253,253,253)，而**白袜子是 237**，
用 246 当背景阈值会把袜子一起吃掉（第一版就吃穿了一只袜子）。
- **人物像站在课桌上**：原场景前景全是课桌，根本没有地面。重出场景：
前景留空地、课桌退到右后方，人物脚下才是地板。
- **自行车 + 步枪**：独立素材 `props/bike.webp`（镜像成车头朝右、与人同向、压白 26%、
自带接触阴影），放在**人物身后偏左**。deco 层顺序 = 画在上面的在前，所以第一层是人、
第三层是车，车天然被她挡住。
- ⚠️ **`background-position` 的百分比是相对 `(定位区宽 - 图片宽)`**，不是相对视口宽。
人（117px）和车（397px）用同一个 `calc(50% - 901px)` 会差出 280px，车直接跑出屏幕只剩一片轮圈。
按各自宽度反解后：人 `calc(50% - 524px)`、车 `calc(50% - 612px)`。
- ⚠️ 道具**不能烘焙进背景**：背景走 `cover`，视口一变裁切量就变，和固定 px 的人物必然分家。
- 场景重出后色调用「逐通道均值/方差对齐旧场景」保持同一雾度；移动端从同图竖裁，避免两个房间。
- `StaticVersion` → `20261020d`；提交 `15aebd6` 已推送。
## 09:55 素材规格书
- 用户打算换工具自己生成素材 → 写了 `docs/theme-shiroko-assets-spec.md`：
画布/导出/显示尺寸、比例（人 1:3.41、道具 1.53:1、背景 16:9）、雾度（人 16%、车 26%、场景 30~38%+模糊 1.2~1.4px）、
构图硬约束（左侧 22% 前景必须是空地，否则又回到"站在课桌上"）、换图清单与定位公式。
- 配色给的是**压白后的显示值** + 反算公式 `原色=(显示值-40.8)/0.84`，并特别标注袜子要用 `#ededed`
而不是纯白（纯白会和背景粘连，抠图必然吃穿）。
## 10:40 主题生成器（dev/theme-builder）
- 单文件 `dev/theme-builder/index.html`：上传背景/人物/道具 → 拖拽调位置 → 导出 zip，
解压到项目根即可新增主题。不联网、不起服务、图片全在浏览器本地转 WebP。
- 预览用**和线上同一套机制**渲染（pattern + deco 6 层 + page-image，size/position 对齐），
不是另画示意图；拖出来的「左沿像素」反解成 `calc(50% - Npx)`，换视口不跑位。
- 导出包：`static/css/themes/<slug>.css` + `static/images/themes/<slug>/*.webp` + `INSTALL-<slug>.txt`。
CSS 同时写浅色/深色两块，10 个必需令牌齐全——**实测通过 `TestThemeCSSComplete`**。
- zip 自己实现（STORE + CRC32，约 40 行），不引 CDN；`unzip -t` 无错。
- 踩坑：① 面板里 `c.text2` 写成 undefined（light 对象里才算出来的派生色，要用 `light.text2`）；
② `contain` 模式如果不按内容裁画布，会留大片透明边 → 导出宽高比全错；
③ 预览容器 `grid-template-columns:340px 1fr` 会被 1512px 的 frame 撑破 → `minmax(0,1fr)`；
④ 无头 Chrome 下 `canvas.toBlob` 的回调在 `--dump-dom` 前不触发 → 全部改 `toDataURL` 同步化，
自检才能跑（`?selftest=1` 输出 CSS/zip 字节，`?demo=1` 载入示例素材）。
- ⚠️ 预览里深色必须走「暗色渐变 + deco none」，否则会拿白天场景图压深底（和导出结果不一致）。
## 11:05 主题生成器重做：真实页面画布 + 按页面作用域
用户原话：旧生成器「只针对当前遇到的问题，需要更通用」「示例页面和我的项目完全不一样」
「想针对箱主页面、问题页面、问题列表、设置页面分别配置」。
**机制层（新）**
- `internal/context.pageScope()` 按路径归类，`<html data-page-scope>`：
`box`(/_/{domain}) / `question`(/_/{domain}/{id}) / `admin`(/user/questions,/user/votes*)
/ `profile`(/user/*) / `vote`(/vote/{token})。首页与 `/explore` 返回了值但**不加载主题 css**，
所以生成器里不列它们（列了就是骗人）。
- ⚠️ 深色覆盖必须是**三重选择器** `html[data-theme="dark"][data-theme-style][data-page-scope]`：
浅色作用域块特异性 0,2,1 与深色块相同、且写在后面，二重选择器会被它盖掉。
- 装饰槽位 **6 → 10**（base.css 背景 8 → 12 层 = pattern1 + deco10 + image1）。
`TestDecoSlotCount` 逐文件逐声明检查，变异验证有效（写 6 个会 FAIL）。
**生成器（重写）**
- 画板 = iframe 加载 `outputs/preview-*.html`（真模板渲染）。**必须起本地服务**：
file:// 下父页面读不到 iframe 的 DOM（即使同目录），预览只能退回示意图。
`dev/theme-builder/serve.py` 把项目根当静态目录（只读）。
- 每个作用域独立「整页背景 + 最多 10 层装饰」，默认跟随全局；不产覆盖块就自动回退。
- 图层 = 图片 / 径向光斑 / 线性光；9 宫格锚点 + 像素偏移；图片层可在画板上直接拖。
- ⚠️ 位置统一 `calc(0%|50%|100% ± Npx)` 两值：百分比是相对 (容器 − 图片)。
**不要** `left/bottom` 关键字混搭 —— 「水平居中 + 垂直贴底」是三值语法，非法时整条声明作废
→ 图层静默掉到左上角（这是之前踩过的坑，这次直接规避）。
- ⚠️ 配色只让填 6 个基础色，另 4 个必需令牌派生：`surface-2` 往 **text** 混（浅色下变深、
深色下变亮，方向自动对），`text-secondary/muted` 往 bg 混，`primary-weak` 加 alpha。
漏了 `--tb-primary-weak` 时 `TestThemeCSSComplete` 只报「缺少」，页面看着没问题，很容易混过去。
- 自检钩子：`?dump=css` / `?dump=zip`（写进 `<pre id="dump">`），配合 `--dump-dom` 回归。
**验证**（都是实测，不是推断）
- 生成器导出的 CSS 放进 `static/css/themes/` → `TestThemeCSSComplete` + `TestDecoSlotCount` 双绿；
删掉深色块做变异 → FAIL，说明测试真的在查。
- 真实箱主页计算样式：image/size/position/repeat/attachment **各 12 层**，前几层尺寸与 shiroko 一致
（auto 400 / 96x13 / auto 259 / 100%×3），确认扩槽没打乱顺序。
- 临时主题 `zztest` 验证：box 页有人物、question 页 `--tb-deco: none×10` 后人物消失；
不写覆盖块时回退全局（人物仍在）。
**顺手发现**：`.gitignore` 写的是 `./outputs`（无效写法），导致 247 个 outputs 文件被跟踪，
每次跑 `TestGenPreview` 都会产生一堆 M。没擅自改（会让人以为要清理历史产物），留待用户决定。
## 12:20 outputs 不再纳入版本控制
- 根因：`.gitignore` 里写的是 `./outputs`，**gitignore 不认 `./` 前缀**，整条规则等于失效，
247 个产物（预览快照、截图、历史 review 报告）一直被跟踪，每次跑 `TestGenPreview` 都产生一堆 M。
- 改成 `/outputs/` + `git rm -r --cached outputs`：索引删除 247 个，**磁盘文件一个没动**。
`git check-ignore -v outputs/x` 确认命中。
- 另两条同样无效的规则没动：`./workbuddy`（目录根本不存在，笔误）、`./scripts`（有 1 个文件被跟踪）。
用户只要求 outputs；要清理得单独确认。
## 13:10 生成器能力盘点（含实测）
用户问「有什么改进建议」，顺手实测了一个之前没验证过的点：**窄屏（390 宽）**。
- 没有 `@media` 规则的主题，在 390×844 下：16:9 桌面背景被 `cover` 裁成一条无意义纹理，
人物被占满屏的卡片完全盖住 —— 等于白配。
- shiroko 因为手写了 `@media (max-width:900px)`（换 `scene-mobile.webp` + deco 全关），
同一视口下背景是协调的竖版、装饰退场。
- 结论：**生成器导出的主题没有窄屏段**，这是真实缺口，不是理论问题。
其它已确认的缺口（grep 过，不是猜）：无 localStorage / 无 json 导入导出（关掉全丢）、
无图层上移下移（遮挡关系由顺序决定，只能删了重加）、无导出前校验、无既有主题导入。
⚠️ 测窄屏时必须让 **iframe 宽度**一起变（`verify.html?w=390`）。第一次只改外层 window，
iframe 内部仍是 1512，媒体查询按 1512 判定 → 结论是错的。
## 14:20 生成器补 P0 四项
用户问建议 → 我给了 P0/P1 清单 → 他选「P0 四条一起做」。已实现并推送。
1. **配置留得住**：`localStorage` 自动草稿（renderAll 后 700ms debounce）+ `theme-<slug>.json`
保存/打开（图片 base64 内嵌，单文件带走）；zip 里也塞一份 json；`?fresh=1` 跳过恢复。
2. **图层 ↑↓**：顺序即层级（`background-image` 第一层画在最上）。
3. **窄屏段**：竖版背景图 + 隐藏装饰 + 断点（默认 900），导出 `@media` 块。
⚠️ **只写浅色规则**：深色块特异性 0,2,1 > 浅色 0,1,1，本来就压住它；多写一份反而容易出错。
4. **导出前校验**：slug / 图片层缺图 / 引用已删素材 / 超 10 层 /
生成 CSS 每处装饰是否真 10 个值（与 Go `TestDecoSlotCount` 同规则，给工具自身兜底）。
**实测**
- 390 视口首层装饰 `url(char.webp)` → `none`，1512 下不变；两种视口都 12 层对齐。
- 草稿往返：带 `?demo=1` 保存 → 不带 demo 打开，`validate` 仍为空（说明恢复成功）。
- 示例 CSS 过 `TestThemeCSSComplete` + `TestDecoSlotCount`（27 处声明）。
**踩到的小坑**
- `makeDemo()` 里 `S.assets.push` 不检查重复 → 重复点「载入示例」会撞 id（`assetById` 取第一个），
导出时静默用错图。改成开头 `S.assets = []`。
- 拖拽标签写 `top:-17px` 会贴到画板边缘被压线/裁切，改成放在框内左上角；
整块半透明填充会把人物罩成一层米色（看着像"框住空气"），改为纯虚线 + 角标签。
- 面板一多左栏就滚不到底：按使用频率重排（图层 → 背景 → 窄屏 → 图片池 → 配色）。
## 15:20 生成器：图片处理（透明度 / 压白 / 去色 / 裁边 / 去白底）
用户问「图片的透明度或者一些简单的处理能否安排上」。已实现并推送 `c3d34b5`。
**非破坏模型（关键设计）**
- `orig` 存上传时的**原始字节**（`FileReader.readAsDataURL`，不重编码），`fx` 只存参数，
每次处理都从 orig 重算 → 「压白 16% → 20%」不会叠加两次 webp 压缩。
- 打开面板看一眼就关：参数没变就**跳过重编码**，一个像素都不动（`fxSnapshot` 比对）。
这条不加，用户点开看看就会把图越磨越糊。
- 预览按 420px 宽算（滑杆跟手），完成时全分辨率重算；用序号 `fxSeq` 丢弃过期结果，
否则快速拖动时旧渲染覆盖新的。
**去白底两个坑（都实测过）**
- 手内侧 / 两腿之间是**闭合**白区，四边漫水进不去 → 按连通域单独掏，面积 ≥ 24 才掏
（更小的多是眼睛高光，掏了变透明洞）。
- **容差默认 16，不是 22**：背景 253、白袜子 237 只差 16。容差 30 实测把袜子吃穿（alpha 0）。
**验证（跑出来的）**
- `?dump=fx` 13 项断言全过：封闭孔开/关、容差 16 保袜子 / 30 吃穿、收边后轮廓 1px、
alpha 50%→128、压白 20% 时 237→241、去色后 R=G=B、裁边 200×160→80×40。
- `?dump=fxpipe` 链路：弹窗开关、预览 300×960、参数重开后仍在、改参后 dataURL 变、
**无改动时 dataURL 一字节不变**（这条是防回归的关键）。
- `?dump=fxkey` 端到端：把 shiroko 立绘合成到 253 白底再去白底，透明占比 46.3%，
与手写 floodfill 抠出来的 46.6% 差 0.3%。
- 生成的 CSS 仍过 `TestThemeCSSComplete` + `TestDecoSlotCount`。
**顺带**
- 工程文件升 v3：存 `orig` + `fx`，未处理时不重复存 dataURL（否则 json 平白翻倍）；
读 v2 旧工程把 dataURL 当 orig 用。
- 新增 `?loadurl=` 把项目里的图直接当素材载入（不必先下载再上传），`?fxjson=` 给初始参数。
- 截图看出两个 UI 问题：拖拽标签 `top:-17px` 贴到画板边缘被压线、半透明填充把人物罩成米色
→ 改框内左上角标签 + 纯虚线（上一轮已修，本轮沿用）。
## 16:10 生成器：图层换不了图 / 背景关不掉 / 草稿清不掉
用户反馈三条，都是**交互设计**问题，核心逻辑其实没坏（实测换图是生效的）。已推送 `937a890`。
- **「每层都只有这张图、换不了」**：`add-layer` 里 `l.asset = S.assets[0].id`，连加三层全是同一张；
而且换图的下拉只在「选中那一层的编辑器」里，用户看不出每层能各自换。
→ 新层不再自动绑图（素材池只剩一张时才绑）；**每行带缩略图 + 「图片」下拉**直接换。
- **「背景关不掉」**：`inherit` 时背景下拉 `disabled` —— 用户在箱主页看到背景还在又点不动。
→ 一律可点，一改自动 `ensureOwn(true)`：切成独立配置 + **把全局当前值复制过来当起点**
（否则改背景会顺带把图案弄丢）；复制图层要**重发 id**，不然两个作用域共用一批 id，拖拽/高亮会串。
- **「上次的数据一直在」**：`localStorage` 草稿只有隐藏参数 `?fresh=1` 能绕过，UI 无出口。
→ 顶栏加「新建」（清空 + 删草稿 + 二次确认）。
⚠️ **跟随全局时不能给拖拽框**：那时 `cfgOf(S.scope)` 返回的是 global 对象，一拖就改到全局去了。
`syncOverlay` 里已加提前 return。同理 `ensureOwn()` 是「任何写操作前」的必调项。
回归（`?dump=layers`）：加层后 `[null,null]`、行内下拉 2 个、换第 2 层后 `[null,blue]` 且 CSS 只出现 blue；
box 页 inherit 时 `addDisabled/bgDisabled` 都 false；在 box 加层后本页 3 层而**全局仍 2 层**；
新建后 assets 0、层 0、草稿已删、scope 回 global。
## 17:5x 生成器：视口自适应 + 导出画质
用户两个问题：插入素材后不同屏幕被裁、导出的 webp 太大。都在 `dev/theme-builder/index.html` 里解决。
**尺寸单位 4 档**（`l.unit`）：`fit`（按视口高，人物）/ `fitw`（按视口宽，横幅）/ `px` / `vh`。
输出 `auto clamp(min(calc(100vh - 24px), 231px), 46.67vh, 420px)` 这种。
- 关键点 1：**内层 `min(视口 - 24px, 基准×55%)`** —— 下限让位给视口，自适应单位因此永不溢出。
写死 55% 下限的话，390 竖屏放不下 1067 宽的图，照样裁。
- 关键点 2：**必须有 `fitw`**。`fit` 只按高度缩，宽幅素材宽度按比例涨：1920×1080 素材 h=600 在
390 视口下 fit 出 1001px 宽（裁），fitw 出 366px（完整）。实测见 `?dump=fit` 的 `fitw` 数组。
- 关键点 3：`layerSize()`（出 CSS）与 `unitGeom()`（出预览框/溢出检测）**必须共用一套换算**，
两套各算迟早漂成「框没超、图已裁」。
- ⚠️ 下拉 value 要用 `l.unit`，不能用 `unitOf()`（把 fit 归一成 vh → 选了 fit 却显示「按视口高比例」）。
**视口预设带高度**（`VIEWPORTS` 改成 `{w,h,label}`，加了 390×844）。原来只有宽度、iframe 恒 900 高，
768 的旧笔电和 844 手机根本模拟不出来 —— 而裁切几乎全由高度决定。
**溢出检测 + 一键修好**：`layerMetrics(l,a,VW,VH)` 给 overL/R/T/B，图层编辑区显示
「1512×900 下显示 131×420，完整可见」或橙色「⚠ 左右各 88px 越界」+「按当前视口修好」按钮
（切 px 并算刚好放下的尺寸）。导出前 `overflowReport()` 再扫一遍，只提醒不拦。
**窄屏每层策略** `l.mob`（inherit/scale/hide）+ 全局 `S.narrow.scale`（默认 0.62）。
⚠️ 顺手修了一个既有 bug：`@media` 块原来只写 `html[data-theme-style]`(0,1,1)，
被页面覆盖块 (0,2,1) 压住 → **独立配置的页面在手机上从来没生效过**。现在每个独立 scope 各写一条。
⚠️ 竖版图只替换 `cfg.bg` 非空的页面（否则给纯色页塞图 = 改了他的设计）。
**背景焦点** `cfg.bgPos` → `--tb-page-position`；base.css 里 `var(--tb-page-position, center center)` 兜底
（旧主题不写也不坏），StaticVersion → `20261020f`。
**导出画质**：`S.export = {quality: 0.88, maxSide: 1600}`，改完全量 `rebakeAll()`（从 orig 重算，不叠加压缩）。
- ⚠️ **`toDataURL('image/webp', 1)` 是坑**：Skia 在 q=1 切无损，输出反常 —— 实测同一张噪声图
q=1 只有 52KB、q=0.95 是 440KB。`canvasAsset` 与滑块都夹到 0.95。
- ⚠️ 平涂/线稿降 q 可能**变大**（有损引入噪点；实测平涂图各档都是 1KB，噪声图 0.6→0.95 涨 75%）。
所以文案写「先砍长边再降质量」，不承诺「降 q 一定更小」。
- 缩小加 `imageSmoothingQuality='high'`。
**自检**：新增 `?dump=fit`（视口占用/溢出/fitw/旧工程兼容/@media 覆盖各 scope）与
`?dump=quality`（q 单调性、q=1 被夹、长边真压像素），两项 `ok:true`；`?dump=validate` 空、layers/fx/fxpipe 全绿。
生成 CSS 临时存成 `static/css/themes/gentest.css` 跑 `go test ./internal/theme` → 30 处声明全过（`clamp` 里的逗号没被当层分隔符）。
⚠️ 顺带发现 **`//go:embed` 的 `*` 不匹配 `_` 开头文件** —— `_scaffold.css` 与 `_gentest.css` 都不进 embed，
所以那个校验一开始"跑了但数字没变"，改名后才真正生效。
UI 踩坑：面板仅 ~240px，`input[type=range]` 有固有宽度 → 必须 `flex:1 1 0;width:0;min-width:0`，
且质量数值要放进 label 里（作第三个 flex 项会被顶出可视区，表现为"滑块没有数字"）。
## 18:2x 排查用户部署的 test01：窄屏素材消失 + 主题名显示成 key
用户自己导出 test01 部署到 box-dev-api（admin6），报两个问题。**两个都复现了，都不是"环境坏了"。**
**测试环境体检（都正常）**：`/_/admin6` 200、`test01.css` 200 且与本地 md5 一致、
`base.css?v=20261020f`（新版，含 `--tb-page-position`）、`<html data-theme-style="test01" data-page-scope="box">`。
部署本身是干净的。
**问题 1：窄屏素材消失** = 工程里「窄屏隐藏全部装饰层」勾着 → 导出 CSS 的 `@media` 把 10 槽全写 `none`。
桌面完全不受影响，所以只看桌面发现不了。定位过程绕了两步弯路，记下来：
- 先怀疑 CSS 表达式非法（`clamp(min(calc(...)),…)`）→ 最小复现页证明**表达式没问题**，图能显示。
- 再怀疑层级：其实素材位置 `calc(50% - 0.67vh)` 正好在**卡片正下方**，卡片 `rgba(255,255,255,0.86)`
只剩 14% 可见，本来就非常淡。
- ⚠️ **本地 preview 快照没有 `data-page-scope`**（TestGenPreview 不走 Contexter），所以
`[data-page-scope="question"]` 覆盖块在快照里根本不生效，读到的是 global 的 `--tb-deco: none`。
本地验证主题必须手动给 `<html>` 补 `data-page-scope`，否则会误判成"主题没生效"。
- 修：删掉 test01.css 的 @media 段（装饰是 fit 单位，浏览器自己会缩）。390 截图确认素材回来了。
- 生成器侧：勾选时橙色警告（几层会消失）+ 图层行标「窄屏隐藏」+ 加层/导出提醒 +
「窄屏」下拉被覆盖时标注；新增 `?narrow=hide` 复现。
**问题 2：设置页显示 `theme.name.test01`** = 模板直接 `{{t .LangCode (printf "theme.name.%s" .Slug)}}`，
`i18n.T` 缺词条返回 key。修：`theme.DisplayName(lang, slug)` 缺词条回退 slug，模板函数 `themeName`。
加了 `TestDisplayName`（自建主题必须回退 slug，不能返回 key）。这样自建主题依旧零改代码。
StaticVersion → `20261020g`（主题 css 内容变了，不换缓存键浏览器 1 天内还是旧文件）。
.workbuddy/memory/2026-10-21.md
-617
View File
@@ -1,617 +0,0 @@
# 2026-10-21
## 扫描者处置方案设计（未实施，仅设计文档）
- 触发：线上频繁收到「疑似批量扫描已自动封禁」告警，命中路径以 wp 探测 + `/.ssh/**` 为主，来源多 Azure 云 IP 池。
- **实测纠正一处错误认知**：`internal/route/route.go:432` 的注释称「flamego 的 NotFound 会先写 404 状态再 Redirect」——
**错的**。flamego v1.9.4 的 `NotFound` 只执行 handler，不写状态码；`ctx.Redirect("/")` 实测输出 **302 → "/"`。
最小复现验证：`/wp-admin/includes/...` 与 `/.ssh/id_rsa` 均得 302 + Location:/。
后果：扫描器跟随重定向 → 每个探测路径都触发一次首页渲染（1C1G 纯浪费），且被判为「站点有价值」。
同时告警邮件文案「产生大量 404」与实际 302 不符。
- 方案分五层（L0 CDN 路径/UA 规则 → L1 真 404 分流 → L2 蜜罐假文件/假凭据 → L3 tarpit + 递进封禁 → L4 上游 abuse 举报）：
- 核心判断：**对云厂商僵尸网络做 IP 封禁无效**，有效的是按**路径**在 CDN 拦 + 蜜罐取证 + 上游举报。
- 明确排除反向攻击/DoS/回打（法律风险 + Azure 共享出口伤及无辜 + 招致 CDN 封站）。
- 蜜罐：命中 `/.ssh/id_rsa`、`/.env`、`/wp-login.php` 等诱饵路径 → 短路返回假内容（含 canary 标记）+ 永久封禁 + 留证。
- 封禁需落库（当前内存 map，重启清零）+ 时长递进 15m→1h→6h→24h→7d→永久 + 多维（IP / IPv6 /64 / UA 家族）。
- tarpit 必须带全局并发上限 + 单连接超时，否则 1C1G 自身变 DoS 入口。
- 设计文档：`outputs/scanner-defense-design-2026-10-21.md`（含分级变更清单、文件级改动点、验收指标）。
- 未动任何生产代码，等用户决定实施范围。
## 蜜罐（虚假后台登录界面 + 破解凭据记录）已实施
用户明确需求原文：「能不能把这些页面指向一个简单的虚假后台登录界面，然后记录这些破解的用户名密码等信息」。
### 落点决策（关键）
- **蜜罐不改写成新中间件，而是改写 `internal/route/route.go` 的 `f.NotFound`**：
- NotFound 只在「路由表完全落空」时触发 → 与 `/login` `/register` `/_/{domain}` `/user/**` `/api/v1/**` 天然零交集；
- 位于全局 `f.Use` 链之后 → `requestBodyLimitMiddleware` 已给 body 加 12 MiB 上限；
- 组级中间件（含 CSRF）只挂具体路由，不作用于 NotFound → POST 表单可安全解析；
- flamego `context.run()` 在 `ResponseWriter().Written()` 为真时 return → 写完响应不调 `ctx.Next()` 即安全短路。
- **双重计数坑**：autoban 中间件对敏感路径已 `Record` 一次，蜜罐再记一次会让阈值实际减半。
解决：`autobanMiddleware(b, hp)` 传入蜜罐匹配器，蜜罐命中的路径由蜜罐自己计数。
### 新增文件
- `internal/security/honeypot/honeypot.go` — 匹配器（段前缀 + 片段子串 + 双重保险 `forbiddenPrefixs` 排除业务路由）、
凭据提取（表单 / JSON / BasicAuth / 查询串）、`CanaryToken = "tb-hp-7f3a1c9e"`。
- `internal/security/honeypot/page.go` — 仿 WordPress 假登录页（经典字段 `log`/`pwd`/`redirect_to`），内联 CSS 不依赖站点静态资源。
- `internal/db/honeypot.go` — `HoneypotHit`（**不嵌 dbutil.Model**，审计证据只追加）+ `HoneypotStore`。
- `internal/route/honeypot.go` — 处理器：GET 假登录页 / POST 假失败响应 / 落库 / 复用 autoban 封禁 / 每 IP 告警一次。
- `internal/cmd/honeypot.go` — `TamaBox honeypot hits|stats|prune`，密码默认脱敏（`--show-password` 显示明文）。
- `templates/mail/honeypot-alert.html` — 告警邮件模板（`mail/` 已在 embed 清单，无需改 embed.go）。
### 改动文件
- `internal/route/route.go`（CRLF）：NotFound 分流 + 蜜罐实例装配 + `hph.sendAlert`。
- `internal/route/autoban.go`（LF）：`autobanMiddleware(b, hp)`，蜜罐路径跳过自身 Record。
- `internal/db/db.go`（LF）：`AllTables` 加 `&HoneypotHit{}`，`Init()` 加 `Honeypots = NewHoneypotStore(db)`。
- `internal/conf/static.go`（CRLF）：`enable_honeypot` / `honeypot_paths` / `honeypot_retain_days`。
- `conf/app.sample.ini`（CRLF）：对应说明段。
- `internal/mail/mail.go`（LF）：`SendHoneypotAlertMail` + `HoneypotAlert`。
- `cmd/tamabox.go` + 根 `tamabox.go`：注册 `cmd.Honeypot`（两处必须同步）。
### 踩坑
- `normalize()` 里 `for len(p)>1 { TrimSuffix(p,"/") }` **无限循环**（路径不含尾斜杠时字符串不变）→ 改成 `HasSuffix` 判断。
- `url.ParseQuery` 遇非法百分号编码返回 error 但仍给出部分字段 → 蜜罐要「尽可能多拿凭据」，忽略 error 继续用部分结果。
- JSON 凭据提取：手写解析器又脏又易错 → 改用 `jsonPairRe` 正则扫描扁平字段。
- `templates/mail/` 已在 embed 清单内 → 新增邮件模板**不需要**改 `templates/embed.go`（顶层文件才需要）。
### 验证
- `go build ./...` 通过；`go test ./...` 全绿（含 DB 测试，postgres 门控）。
- 新增测试：`internal/security/honeypot/honeypot_test.go`（匹配/业务路由零交集/编码绕过/凭据提取）、
`internal/route/honeypot_test.go`（假页含 canary、业务路由不被劫持、关闭时回落 302、POST 返回失败页）、
`internal/db/honeypot_test.go`（写入/倒序/三张聚合表/保留期清理）。
## 测试站黑盒验证 + P0 缺陷修复（蜜罐封禁被 enable_auto_ban 连坐）
测试站：`https://box-dev-api.337845818.best`（Cloudflare Tunnel + CF 边缘，`cf-cache-status: DYNAMIC`、无 `Age` → 不缓存，请求确实回源）。
生产站 `https://box.tama.guru` 强制 301 → www，本机不可达，无法做对照。
### 黑盒验证结果（全部通过）
- 诱饵路径全部 200 + `text/html`：`/wp-login.php` 2529B、`/wp-admin/` 2517B、`/.ssh/id_rsa` 2525B、`/.env` 2497B、`/administrator` 2533B。
- 响应体含 canary `tb-hp-7f3a1c9e`（2 处）、`<title>Log In ‹ WordPress</title>`、`name="log"`/`name="pwd"`/`name="redirect_to"`。
- 响应头：`Cache-Control: no-store, no-cache, must-revalidate`、`x-robots-tag: noindex, nofollow`、`x-frame-options: DENY`。
- POST 凭据提交 → 200 + `id="login_error">ERROR: Invalid username or password.`。
- 路径变体全命中：`/WP-ADMIN`（大小写）、`/wp-admin%2f..%2fetc`（编码绕过）、`//wp-admin//x.php`（双斜杠）、`/.git/config`、`/.aws/credentials`、`/phpmyadmin/`、`/actuator/env`、`/xmlrpc.php`、`/vendor/phpunit/x.php`、`/console`、`/cgi-bin/test.cgi`、`/wp-content/plugins/x.php`、`/.env.bak`、`/wp-json/wp/v2/users`。
- 凭据来源全覆盖：表单 POST、JSON body、BasicAuth、查询串、POST 到 `/.ssh/id_rsa`。
- **业务路由零交集（红线）**：`/` 34192B、`/login` 23420B、`/register` 25194B、`/_/admin6` 39358B、`/user` 302、`/api/v1/questions` 302、`/robots.txt` 145B；非诱饵随机路径 `/nonexistent-random-xyz` 仍 302→`/`。
### P0 缺陷：蜜罐命中 70+ 次但站点零封禁
- 根因：`autoban.Record()` 第一行 `if !b.enabled { return }`，`b.enabled` 来自 `enable_auto_ban`。
运维为避免共享出口误伤而关掉 `enable_auto_ban` → **蜜罐被另一个开关连坐**，只落库不封禁。
- 对照组证明非蜜罐专属：`/index.php`（autoban 敏感、蜜罐不匹配）连打 40 次 + 30 并发同样零封禁。
- 排除项：CF 缓存（DYNAMIC/无 Age）、flamego NotFound 链（源码确认全局 Use 链生效）、蜜罐匹配器、阈值配置。
**修复（已实施，测试全绿）**：
- `autoban.Options` 新增 `HoneypotEnabled` / `HoneypotThreshold`（默认 1）/ `HoneypotDuration`（默认复用常规）。
- 新增 `Banner.RecordHoneypot(ip, path) bool`：独立计数、独立阈值，**不受 `enabled` 约束**；键与 `Record` 一致（同样 `shared.LimitKey` 归一化），否则 `IsBanned` 判不出来。
- `IsBanned()` 移除 `!b.enabled` 早退 —— `enabled` 只控制「是否主动创建封禁」，不控制「是否尊重已有封禁」。
- `internal/route/honeypot.go`：`banned = h.ab.RecordHoneypot(ip, path)`。
- `internal/route/route.go`（CRLF）装配三个蜜罐字段；`conf/static.go` + `conf/app.sample.ini`（CRLF）新增 `honeypot_threshold` / `honeypot_ban_minutes`。
- 告警：仍走既有 `sendAlert`（「已封禁」）+ 蜜罐自己的告警邮件（「捕获了什么凭据」），互补。
### 后缀匹配补缺
- `/backup.zip`、`/db.sql`、`/id_rsa.pem` 这类泄露扫描文件名主体随机，**只有后缀稳定**。
- 原 `honeypotFragments` 用 `"/.zip"` 子串匹配 → `.zip` 前是 `k` 不是 `/`，全漏网。
- 新增 `honeypotSuffixes`（`.zip .tar .tar.gz .tgz .gz .rar .7z .bz2 .sql .sql.gz .dump .bak .old .orig .save .swp .env .env.bak .env.local .pem .key .p12 .pfx .jks .kdbx .ovpn`），按 `path.Base()` 结尾匹配。
### 踩坑
- ⚠️ **测试里 `Duration: 60` = 60 纳秒**，封禁瞬间过期 → 表现为「时序巧合的 200/200/403」，测试假失败。一律写 `60 * time.Minute`。
- ⚠️ 路由测试只注册路由 + NotFound 会被绕过：执行 `IsBanned` → 403 的是 **`autobanMiddleware`**，测试服务器必须 `f.Use(autobanMiddleware(ab, hp))`。
- ⚠️ `internal/route/route.go`、`internal/conf/static.go`、`conf/app.sample.ini` **实际是全 CRLF**；`grep | cat -A` 不显示 `^M`，极易误判为 LF。Python 脚本按 `\n` 锚点替换会静默失败 → 用 `\r\n` 锚点 + 写后统计 `b'\r\n'` 复核。
- 假页纯静态 HTML（内联 CSS，不落盘）、告警走 SMTP → **取证数据只在 `honeypot_hits` 一张表**，服务器无文件副本；autoban 封禁表是内存态（重启清零）。
- 测试阶段产生的噪声凭据（`testadmin/S3cr3tP@ss` 等）可用 `TamaBox honeypot prune` 清理。
### 遗留（需用户侧）
- 本轮修复需**重新部署**才在测试站生效；部署后 `curl` 一次 `/wp-login.php` 应 200、再一次 403。
- 需确认测试环境 `conf/app.ini` 的 `[security] enable_auto_ban`（零封禁直接原因）+ `enable_honeypot = true`。
- 无法 SSH（`100.79.185.45:19999` 全部账号 Permission denied），落库验证需用户执行 `TamaBox honeypot hits --since 24h --show-password`。
---
## 蜜罐表体积实测 + 自动清理（commit 63e851d，已 push）
用户问「这些记录会不会导致数据库很臃肿」。**不靠推断，本地 PostgreSQL 建同构表灌仿真数据实测。**
### 实测数字
- 典型行 **244 字节**（heap 201 + 索引 43），10.5 万行 = 24 MB；常规 UA 下实测 281 B/行。
- 字段均值：path 13B、user_agent 111B（单行最大头）、fields 3B、raw_body 3B。
- `raw_body` 被 `maxCredentialFieldLen = 512` 截断，故字段数量随之受限（200 字段场景 rawBody 仍 512B）。
- 最坏情况（手工构造 50 字段 × 500B）约 2375 B/行。
- **UA 截短收益**：截到 100 省 1129 kB / 截到 64 省 4824 kB（10 万行）→ 仅 5–20%，
远小于自动清理的确定性上界且损失取证信息 → **决定不做**。
### PostgreSQL 死元组语义（本轮最关键认知）
- `DELETE` 只标记死元组，**表文件不会变小**；空间需 VACUUM 后才可被后续 INSERT 复用。
- 对照（10 万行，每轮删 25% 插 25%，行数恒定）：有 VACUUM 22→24 MB **收敛**；无 VACUUM 22→52 MB **膨胀**。
- ⚠️ **VACUUM 不缩小文件，只让空间可复用**。二次实测（5 万行、连续 4 轮删 12000 插 12000）：
行数恒定 5 万、文件稳定 15 MB 不再增长 —— 这才是要的效果（止住增长，不是让文件变小）。
想让文件立刻变小只有 `VACUUM FULL`（重建整表 + 锁表），蜜罐表万级行没必要。
- ⚠️ `VACUUM` **不能在事务块内执行**（SQLSTATE 25001），也不能在 PL/pgSQL 函数体内执行（VACUUM 无法从函数执行）。
GORM `db.Exec()` 走 `callbacks.Raw()` 处理器、**不包事务** → `WithContext(ctx).Exec("VACUUM ...")` 可用（已实测）。
- PG18 已移除 `pg_stat_user_tables.n_tup_vacuum`，改用 `last_vacuum` 验证。
### 索引实测（EXPLAIN 驱动决策）
- `idx_honeypot_hits_provider`：10 万行 648 kB，**全代码库零查询使用**（TopSources 用 max(provider) 随 group by 顺带取）→ 已删。
- `idx_honeypot_hits_created_at`：EXPLAIN 显示 `Index Scan Backward`，被 `ListSince` 实际使用 → 保留。
- `idx_honeypot_hits_ip`：4.7 MB（最大），但 GROUP BY ip 走 Seq Scan + HashAggregate；**保留**（`ListSinceByIP` 需它）。
- ⚠️ **GORM 去掉 struct tag 的 `index` 不会删除既有库上的旧索引** → 需显式 `HasIndex` + `DropIndex`（已加 `dropUnusedHoneypotIndexes`，启动时跑，失败仅告警）。
### 落地改动
- `internal/db/honeypot_retention.go`（新）：`HoneypotRetention` 后台清理器，每小时一轮，两道闸
（时间 `honeypot_retain_days` + 数量 `honeypot_max_rows`）→ 清理后调 `Compact()`。
保留期 <=0 视为不自动清理（只告警）；**`runOnce` 开头必须再挡一次 `retainDays<=0`**，
否则 before=now 会把历史全删光（「保留 0 天」被误解释成「只留此刻」）。
- `internal/db/honeypot.go`（新方法）：`Compact()`（PG `VACUUM (ANALYZE)`）、`DeleteOldestBeyond()`
（跨方言通用，子查询按 id 倒序取 keepRows 边界）、`ListSinceByIP()`、`Size()`。
- `internal/cmd/web.go`：接入清理器，`stopRetention` 用 defer close。
- `internal/cmd/honeypot.go`：新增 `honeypot size` 子命令（行数/磁盘占用/时间跨度 + 与两道闸对照）。
- 修 CLI `hits --ip` 真 bug：原先取回最近 N 条再在 Go 侧筛 → 指定 IP 的历史命中基本查不出来 → 改 SQL 层过滤。
- 新配置：`honeypot_auto_clean`（默认 true）、`honeypot_max_rows`（默认 200000 ≈ 53 MB）。
### 踩坑
- ⚠️ 测试预期别自己推算错：`DeleteBefore` 是**严格小于**（`created_at < before`），边界那条不删。
- ⚠️ Python 补丁脚本里写 Go struct tag 的反引号 → bash 命令替换报错，**必须写成 .py 文件执行**（不能 `python -c`）。
- ⚠️ `psql` 传中文 SQL 报编码错 → 用英文输出串或 `PGCLIENTENCODING=UTF8`。
- ⚠️ 库名带连字符要用双引号：`CREATE DATABASE "tamabox-cli-test"`。
- ⚠️ Edit 工具改 CRLF 文件会保持 CRLF，但**改写时我打的字会转码损坏**（出现过「实测指事/程定/不图」）→ 改完必须逐行读回复核。
- 仓库内统一存 LF，工作区 CRLF 由 `core.autocrlf=true` 自动转换 —— 提交时 warning 属正常，不是行尾被改。
---
## 配置键名静默失效的根治（commit d300167，已 push）
### 现场故障
用户配置 `honeypot_retention_days <= 30`，日志报「蜜罐自动清理未启用：honeypot_retention_days <= 0」。
### 根因（探针实测 ini v1.67.0，不是读源码猜的）
1. **键名多一个 t**（retention vs retain）→ ini 对未知键**静默忽略**，保留期成 0。
2. **`<= 30` 这种写法**让 ini 把键名解析成 `"honeypot_retention_days <"`（带尾随比较符），
实测输出：`key="honeypot_retention_days <" value="30"` —— 更匹配不上。
3. **我之前那条警告文案里写的也是错键名** `honeypot_retention_days`，
等于在误导运维往错的键上配 —— 教训：警告文案里的键名必须与代码读的键名逐字一致。
### 实测到的 ini 行为（重要，写 ini 相关代码前必读）
- `MapTo` 在**键缺失或值非法时不覆盖**目标字段 → 可以安全预置缺省值。
- 键名**大小写敏感**（`Honeypot_Auto_Clean` 不生效）。
- `HasKey` 能区分「缺失」与「显式 0」。
- 段不存在时 `MapTo` 返回 nil 且不修改目标。
- bool 的解析是「有键才赋值」→ **未配置与显式 false 无法用零值区分**，必须靠 HasKey。
### 修复三层
- `internal/conf/keynorm.go`（新）：键名归一化（修剪空白、剥尾随 `<` `>` `=`、别名表纠错）。
⚠️ 归一化结果必须命中该段**合法键名白名单**才采用 —— 不认识的键不猜，交给未知键告警。
- `internal/conf/unknown.go`（新）：启动逐段比对键名，未知键 WARN + 给出最接近的合法键名。
合法键名由**反射从结构体 ini tag 得出**（单一事实来源，新增配置项自动纳入）。
- `internal/conf/honeypot_defaults.go`（新）：蜜罐缺省值语义修正
（保留期缺省 30、auto_clean 缺省 true 用 HasKey 判、max_rows 缺省 200000、threshold 缺省 1）。
- 归一化必须在 `MapTo` **之前**做 —— 等 MapTo 跑完，错拼的键早被丢掉了。
### 顺带清理
`app.sample.ini` 里两条死配置：`app.title`（代码从未读，站点标题走 i18n `site.title`）、
`server.xsrf_expire`（无对应字段）。留着会让新检测对官方模板误报。
### 踩坑
- ⚠️ **Python 脚本里写 Go struct tag 的反引号** → bash 命令替换报错。
改用 Edit 工具逐处改（Edit 对 CRLF 文件保持 CRLF，但**我打的字可能转码损坏** → 改完逐行读回复核）。
- ⚠️ `gofmt -l` 对 CRLF 文件一律报警（gofmt 要求 LF）—— 那是既有状态，不是我的改动。
- ⚠️ 我自己的测试预期写错过两次（别名生效后的期望值、static_version 不是 ini 键）。
**测试失败要先怀疑自己的预期**，别急着改产品代码。
## 蜜罐实现审计（第三方 agent 写完，我复审）
### P0：蜜罐封禁整条链路未接线（已实测复现）
`internal/route/route.go:85` 的 `autoban.New(...)` **没传** `HoneypotEnabled / HoneypotThreshold /
HoneypotDuration`，而 `autoban.RecordHoneypot` 首行就是 `if !b.honeypotEnabled { return false }`
→ 蜜罐命中永不封禁、落库 `banned` 恒 false、`IsBanned` 永不为真。
同一提交又把 `autobanMiddleware` 里蜜罐路径的**常规计数也跳过**了
（`route/autoban.go:38 if hp == nil || !hp.Match(path)`，理由「蜜罐处理器自己计数」）
→ 净效果：蜜罐路径从「10 次封禁」退化为**零计数零封禁**，是 regression。
`honeypot_threshold` / `honeypot_ban_minutes` 两个配置项全代码库**零读取**（死配置，样例 ini 里却写了）。
测试为什么绿：`route/honeypot_test.go` 自建 banner 时显式传了 `HoneypotEnabled`，
注释还写着「与 route.go 一致」—— 实际不一致，测试绕过了生产装配。
### P1
- 蜜罐 GET 探测（无凭据）也逐条 INSERT，把「零成本 404」变成「每请求一次 DB 写」，
且 NotFound 链路上没有 rate limit → 扫描器可直接放大成 DB 写压力；20 万行闸每小时才跑一轮。
- `honeypotHandler.alerted`（map[string]bool）无 TTL、无清理，随源 IP 数量无界增长；
autoban 的同名 map 也是（既有问题，蜜罐放大）。
### P2
- `Path` 原样落库但列是 `size:512` → 超长路径直接 PG 报错丢证据；`Query` 用 `query[:1000]`
字节截断，`honeypot.go:243/296` 的 `v[:limit]`、`raw[:limit]` 同样是字节截断
→ 多字节字符被切半产生非法 UTF-8，PG 拒插。同文件里已有按 rune 的 `truncate()` 却没用于这些点。
- `credentialKeys` 含 `id` / `name` / `token` → 任意 JSON 探测带 `{"id":1}` 就会被当成「破解凭据」
触发告警邮件 + 记为 HadFields，污染取证与告警。
- `page.go:54` `<meta name="generator" content="TamaBox honeypot tb-hp-7f3a1c9e">` 把「这是蜜罐」
和「这是 TamaBox」同时明示给扫描器（nuclei 类模板可据此跳过）。
- `serveLoginFailure` 手抄了一遍 `WriteLoginPage` 的响应头逻辑（没复用），已开始漂移
（Title 一处写 `‹`、一处写 `\u2039`）。
- `Honeypot.Describer()` 零调用死代码，且 `path.Join(keys...)` 语义错误（会把前缀拼成一条路径）。
### 结论
总体设计（挂 NotFound、零业务交集、只回假内容、脱敏 CLI、独立取证表）方向正确；
问题集中在「装配层没接上」与「写入侧的边界处理」。P0 必须先修，否则蜜罐只是个记日志的旁观者。
## 蜜罐审计问题的修复实施（已改完，未提交）
### 1. P0 装配（route.go）
抽 `newBanner()` 作为唯一装配入口，补 `HoneypotEnabled / HoneypotThreshold / HoneypotDuration`。
新增 `internal/route/banner_config_test.go` 四个用例，全部经由 `newBanner()` 断言。
**变异验证**：分别把 HoneypotEnabled 改成 false、Threshold 改成 0，对应用例确实失败。
### 2. 诱捕语义修正（审计时漏掉、比 P0 更影响功能价值）
原实现 `RecordHoneypot` 对**所有方法**计数且阈值 1 → 扫描器 GET 一次假登录页就吃 403，
永远走不到「POST 提交凭据」那一步，蜜罐核心价值（拿字典）直接归零。
改为：`creds.HadFields` → RecordHoneypot（立即封）；纯探测 → 常规 `Record`（阈值 10）。
新增 `TestHoneypotProbeDoesNotBanImmediately`，同上做了变异验证。
连带把 `honeypot_threshold` 的语义在 static.go / defaults / autoban / sample.ini 统一为
「提交凭据次数」。
### 3. 落库边界（实测取证）
- `Path` 原样落库、列宽 512 → PG `SQLSTATE 22001 值太长了(512)`，整条证据丢失；
实测 600 字符失败、500 字符成功。
- 三处按字节截断 → `SQLSTATE 22021 无效的 "UTF8" 编码字节顺序`（中文密码/URL 可稳定触发）。
全部改为 rune 截断（`clipRunes` / route 的 `truncate`），并按列宽逐个对齐。
### 4. 资源与噪音
- `honeypotHandler.alerted`（无界 map）→ 换成带 TTL 的 `deduper`（容量上限 2 万，
过期清理 + 超限硬裁），同时承担「告警 24h 冷却」与「纯探测落库采样（每 IP 每分钟一条）」。
- `credentialKeys` 去掉 `id` / `name`（普通 JSON 探测不再被当成凭据提交触发假告警）。
- canary 从 `<meta name="generator">` 移到 HTML 注释（`<!-- build: ... -->`），
generator 伪装成 `WordPress 6.4.3`；不再向扫描器自曝「TamaBox 蜜罐」。
- `serveLoginFailure` 不再手抄响应头，统一走 `WriteLoginPage`；`LoginPageTitle` 抽常量。
- `Describer()` 死代码 → 改为 `Prefixes()` 并接到新 CLI `TamaBox honeypot paths`。
- `honeypot_paths` 解析挪到 `honeypot.SplitPaths`（CLI 与 route 共用），补前导斜杠、拒绝 `/`。
### 5. 新发现的配置陷阱（影响面比蜜罐大）
`conf.Init` 用 `ini.LoadOptions{IgnoreInlineComment: true}`，该选项语义是
**不剥离行尾注释**（实测：`port = 1440 ; 注释` → 值 `"1440 ; 注释"`，int 解析失败，
`MapTo` 却返回 nil error）。后果：
- `app.sample.ini` 照抄**无法启动**（`text_censor_source` 值带注释被 validate 拒绝）；
- 所有带行尾注释的 int/bool 静默回退零值 —— `enable_auto_ban`、`honeypot_max_rows`、
`honeypot_auto_clean` 全部中招（后两者靠 sanitize 兜底才没出事，max_rows 则真的失效）。
已把 sample 的**蜜罐段**改成「注释独占一行 + 裸值」，并在段首写明原因。
其余段落仍是老写法，未动（需用户决定是否全面清理）。
### 待办
- 用户确认是否提交这批改动。
- `app.sample.ini` 其余段落的行尾注释问题未修，建议后续统一。
- 蜜罐 GET 探测目前受 `enable_auto_ban` 约束（关了就不计数），这是有意的：
纯探测无害，不该在运维关掉自动封禁后仍凭空封人。
## 后续：sample 注释清理 + 凭据外置（同日晚）
### 1. app.sample.ini 行尾注释全量清理
17 处 `key = value ; 注释` 改成「注释独占一行 + 裸值」，保留 CRLF。
新增 `TestSampleIniValuesHaveNoInlineComment`：遍历所有段的键，断言 `Value()` 不含 `;`。
变异验证：把 `ban_window_seconds = 60` 改成带行尾注释 → 测试按预期失败。
清理后 `conf.Init` 读 sample 的报错从「值含注释」变成「server.xsrf_key 未填」，
说明解析路径已通（必填项留空是模板的预期行为）。
### 2. 凭据改为外部文件，数据库不再存用户名/密码
- `honeypot.CredRecord` + `CredStore`（`internal/security/honeypot/credstore.go`）：
按天分文件 `creds-YYYY-MM-DD.jsonl`，一行一条 JSON；目录 0700、文件 0600；
坏行跳过；`PurgeBefore` 只删「整天都早于保留期」的文件。
- `db.HoneypotHit` 删掉 `Username/Password/Fields/RawBody`，只留 `HadFields` 元数据。
- `HoneypotStore` 删掉 `TopCredentials` / `ListSinceByIP`（CLI 已改读文件，零调用）。
- 新增 `LegacyCredentialColumns` / `PurgeLegacyCredentialColumns`：
AutoMigrate 不删既有列，老库会残留历史明文 → 启动时 WARN，`honeypot purge-creds` 显式 DROP。
- 清理器 `HoneypotRetention` 加 `CredPurgeable` 参数，与 DB 记录共用保留期；
`honeypot prune` 也一并删过期凭据文件。
- CLI：`hits` 不连 DB（DB 挂了也能查），`stats` 的凭据排行读文件，新增 `purge-creds`。
- 配置 `[security] honeypot_cred_dir`，缺省 `data/honeypot-creds`；`.gitignore` 加 `/data/`。
### 测试
`credstore_test.go`（追加/倒序/IP 过滤/坏行/Top/Purge/权限）、
`TestHoneypotLegacyCredentialColumns`（ADD COLUMN 模拟老库 → 检测 → DROP）、
`TestHoneypotWritesCredentialsToFile`（POST 后文件有记录）。
CLI 端到端手动验证：`honeypot hits` / `--ip` / `--show-password` 输出正确。
全量 `go test ./...`（含 PostgreSQL）通过。
### 遗留
- **历史备份/主从复制里可能仍有旧明文凭据**，代码无法处理，需运维自行清理。
- 邮件告警仍会带明文用户名/密码（用户未要求改）。
### 已提交（2026-10-21，未推送）
- `566b13e` fix(conf): 样例配置去掉行尾注释（2 文件）
- `c29e1d0` fix(honeypot): 补齐封禁装配与诱捕语义，凭据外置为文件不再入库（21 文件）
- `main` ahead of `origin/main` 2；用户要部署测试环境验证后再决定推送。
### 测试环境实测反馈（同日晚，已修并推送）
现象：purge-creds 删 4 列成功、GET 200、POST 后 GET 403、文件已生成。
但凭据文件里 `"path":" /wp-login.php"`（前导空格）、`"ip":"127.0.0.1"`。
- **path 脏字符**：反代链路（CF → nginx → 源站）传出的 `req.URL.Path` 带前导空白。
`Match` 内部 normalize 会 TrimSpace 所以仍命中，但落库与假表单 action 用原始值
→ 取证数据脏、爆破脚本可能提交到错误路径。本地 httptest 复现不出来，是环境相关。
修复：`cleanPath()` 在 Serve 入口 trim + 补前导斜杠（不改大小写）。
- **IP = 127.0.0.1**：说明 `trust_proxy` 未开。后果不只是取证失真 ——
**一次蜜罐封禁会封掉 127.0.0.1，等于封掉整站所有访客**（封禁是内存态，重启即恢复）。
修复：命中回环地址且 `!trust_proxy` 时打一次性 WARN（24h 冷却），不改封禁行为。
sample.ini 的 trust_proxy 段补了蜜罐相关说明。
- `846bb8a` 已推送（`5e8deca..846bb8a`）。
### 收尾：path 脏字符最终定位（同日晚）
用户重启进程后，`od -c` 显示新记录的 `"path":"/wp-login.php"` —— 干净。
说明之前那条带空格的是**旧进程**写的（16:07 那次 `./tamabox web` 并没有真正替换掉在跑的实例）。
期间补了两处加固并推送：
- `74312fb`：`cleanPath` 改用 `TrimFunc` 覆盖 U+200B/200C/200D/FEFF
（`TrimSpace` 只认 White_Space，零宽字符会漏，且会因首字符不是 `/` 多补斜杠）；
清洗前后不一致时 WARN 打出 `%q` 原始值，不可见字符靠日志才定位得到。
- 教训：`strings` 不认 UTF-8 中文（已记入 topics/build.md）；替换二进制后必须重启进程。
### 文档（`3d45374`，已推送）
- 新增 `docs/honeypot.md`：生效范围、配置、**两条封禁路径**（GET 走常规阈值 /
提交凭据才即封）、凭据文件格式与不入库的理由、`trust_proxy` 部署必读、
旧列清理、排障表、设计取舍。
- `docs/cli.md`：§0 补「替换二进制必须重启」「strings 用 grep -ac」；
命令总览加 honeypot；新增 §7 honeypot 命令（原 7/8/9 顺延为 8/9/10）；
排错表加 5 条。
# 2026-10-21
## 新旧前端对比（正式 vs 测试环境），只测量未改码
**方法**：curl 抓两环境 4 个页面 → 本地注入脚本取计算样式 / 资源体积 / 对比度 / 点按区；
无头 Chrome 截图（`--headless=old`）后用 Pillow 算像素指标。
⚠️ 本模型读不了图片，所以结论全部来自数值与结构，不靠"看截图"。
**踩坑**：file:// 打开抓下来的页面时，`href="/static/css/base.css"` 会解析成 `file:///static/...` → CSS 不加载，
于是 dev 页量出来全是 UIkit 旧样式（圆角 0、旧阴影）。改法：抓下来后把 `/static/` 重写成 dev 域名绝对地址，
再重新采集。**以后本地复现线上页面必须先重写站内绝对路径，否则测的是"无 CSS 的裸 HTML"。**
另：`body.scrollWidth` 会被隐藏面板撑大（dev explore 1499），判断横向溢出要看 `documentElement.scrollWidth`（实测 1249 = 无溢出）。
**实测差异（1280 宽）**
| 指标 | 正式（旧） | 测试（新） |
|---|---|---|
| 首页 HTML | 42.9KB | 34.2KB |
| 探索页 HTML | 77.4KB | 53.4KB |
| `<style>` 块 | 9–10 | 2 |
| 行内 style 属性 | 8–16 | 3–5 |
| 卡片圆角 / 阴影 | 0px / 单层硬阴影 | 12px / 双层柔阴影 |
| 圆角取值种类 | 2px×73、50%、8、6、4、9 | 6、8、12、14、5、50% |
| 正文色 | #333/#666/#999 混用 | 令牌 #1f2329/#5c6370/#8a919c |
| 字体栈 | UIkit 默认 | system-ui + 苹方/雅黑 |
| 图标 | emoji（🌙☀️） | 内联 SVG |
| 首页截图像素：色彩数 / 边缘密度 | 2206 / 10.3% | 1174 / 5.0% |
**共同短板（新旧都没解决）**
- `--tb-text-muted #8a919c` 在 #fff 上只有 **3.18:1**（AA 需 4.5）；旧版 #999 更低（2.85）。
建议改 #6b7280（4.83:1）；暗色 muted #8b93a1 在 #242830 上 4.77 已达标。
- 顶栏导航链接（UIkit rgba(0,0,0,.5)）2.68–2.85:1，同样是低对比。
- 移动端点按区：两版都有大量 19px 高的纯文字链接（不满足 44px 建议值）。
**新版自身的毛病（我写的，待修）**
- `templates/home.html` 字号用了 0.75/0.78/0.86/0.9/0.95/0.98 rem → 7 个肉眼难辨的档位；
`static/css/base.css` 里还有 0.78/0.8/0.82/0.84/0.88/0.95。**排版层级比旧版更碎**，应收敛到 4 档。
- 残留圆角 5px（header 验证码框、sponsor）、9px（profile-tabs，list.html/explore.html 各一处）。
## 按上轮结论改代码（字号收敛 / 对比度 / 圆角收敛）
先确认过：本地 `static/css/base.css` 与 dev 部署版 **diff 0 行**，本地就是新版基线。
1. **新增字号阶梯令牌**（base.css `:root`）：`--tb-fs-xs/md/lg/xl/hero` = 12/14/16/24/28px。
`lg` 取 **1rem 而非 17px** —— UIkit 的 `.uk-card-title`/h4 就是 16px，顺着它才能让自定义标题
与组件标题同档，否则会留下 16 与 17 差 1px 的两档并存（第一版就是这么写的，实测发现后改回）。
2. **替换范围**：home.html 全部 7 档 → 5 档；explore / question-list / question-list(list.html) 三页
的 0.7/0.72/0.82/0.84/0.85/0.9/0.98/1/1.15/1.2 全换令牌。实测 explore 由 **9 档 → 5 档**。
3. **`--tb-text-muted` #8a919c → #6b7280**（#fff 上 4.83:1）。**关键坑**：
UIkit 自带 `.uk-text-muted{color:#999!important}`，我原先的普通声明**从未生效**，全站仍是 #999（2.85:1）。
必须 `!important` 才能压过。改完 box 页 fails 15→11、explore 14→9。
4. **顶栏导航**：UIkit 默认 rgba(0,0,0,.5) = 2.68:1 → 改 `var(--tb-text-secondary)` = **6.05:1**，
hover/active 走主色；暗色分支原有 `!important` 规则自然接管（实测 10.75:1）。
5. **圆角全量收敛**：9px/5px/4px/2px/7px/3px 以及等值的 6/8/10/12/14px 全部换成
`var(--tb-radius[-sm|-xs])`。全站（排除邮件模板）现在只剩 3 处 `999px`（胶囊，语义正确）。
6. `conf.StaticVersion` 20261020g → **20261021a**（base.css 改了必须 +1）。
**验证**：go vet / go test（templates+i18n+conf）/ go build 全绿；预览页内联本地 base.css 后用无头 Chrome
量计算样式，首页 12/14/16/24/28、explore 12/14/16/24/32，nav 6.05:1。
**遗留（未改，属设计取舍）**：主色链接 `#1e87f0` 在纯白上 3.37–3.42:1（<4.5）。改深会影响品牌观感，
需用户决定；Waline 第三方赞数绿色 2.87 不在本站控制内。
**注意**：工作区有 4 个**非本次改动**的删除（`static/css/themes/test01.css`、`static/images/shiroko-cutout.png`、
`static/images/themes/test01/*.webp`），是之前就存在的未提交删除，提交时勿一并 add。
## 17:4x 用户前端设计令牌化 → 主题/生成器的连带影响
用户改了 12 个模板 + base.css（未提交）：`--tb-text-muted` #8a919c→#6b7280（AA 4.83:1）、
新增 `--tb-fs-xs/md/lg/xl/hero` 阶梯、圆角改走 `--tb-radius(-sm/-xs)`、顶栏链接改 `--tb-text-secondary`、
`.uk-text-muted` 加 `!important`（压 UIkit 的 `#999!important`）。
**关键结论：主题会把这套修复盖回原样。** 主题 css 覆盖同名令牌 → 页面用主题的值，不是 base.css 的。
实测（worse of bg / 压平后的 surface）：
- default.css 不定义文字色 → 跟随 base ✓；sakura muted `#a08c94` **2.80:1**、shiroko `#8794a7` **2.76:1**（都看不见）。
- 已调到 AA 下限：sakura `#78696e`(4.61)、shiroko `#656e7a`(4.63)，同色相只压深；深色块两个主题本来就 ≥4.7，不动。
- 主色仍不达标（未改，等用户定）：base/shiroko `#4a7fc1` 3.69、base `#1e87f0` 3.26、sakura `#e5678f` 2.80。
候选：`#3d6fac`(4.63)、`#0f6ac6`(4.83)、`#b53d61`(4.91)。
**生成器的必修项**：`paletteVars` 原来 `text-muted = mix(text,bg,0.55)` 硬算 → 浅底掉到 2.9:1，
等于每导一次主题就把 base.css 的修复覆盖掉。改成 `mixToContrast(text, [bg, flatten(surface,bg)], 4.5)`：
二分找「最淡但达标」的比例；文字本身不达标时原样返回（宁可不够淡，不能看不见）。
- 半透明卡片（`rgba(255,255,255,0.86)`）必须**压平到底色**再算，否则按纯白算会偏低。
- 次要 5.5 / 弱化 4.5 两档，保证层级不倒挂。
- 配色面板加读数 `正文 12.5:1 · 次要 5.5:1 · 淡文字 4.6:1 · 主色 4.6:1`，<4.5 变橙（手填主色只提醒不拦）。
- 默认 primary 由 `#4a7fc1`(3.69) 压到 `#3d6fac`(4.63) —— 默认值不该一上手就踩线。
- 新增 `?dump=palette`（四种配色：默认亮/默认深/低对比手填/白卡彩底），`ok:true`。
**顺手补的一致性**：深色块顶栏原来 `!important` 定成 `--tb-text`（正文色），亮色块新的 secondary 规则
让同一顶栏在深浅两模式权重跳一档 → 加 `html[data-theme="dark"] .uk-navbar-nav > li > a { secondary !important }`。
实测计算值：无主题 nav #5c6370 / muted #6b7280；shiroko #51607a / #656e7a；sakura #6b545c / #78696e。
**⚠️ 用户删了 test01（css + 2 张图）与 `shiroko-cutout.png`，未提交，我没动。** 若测试站 `[theme] available`
还登记着 test01，启动日志会打「主题文件不存在，已从可用列表忽略」，设置页不再出现，箱主已选 test01 的会静默回退站点默认。
`shiroko-cutout.png` 只在 `docs/theme-shiroko.md` 里作参考图引用，不参与 embed。
**令牌化的残留**（只提醒，没改）：`templates/user/profile.html` 还有 16 处 `font-size: 0.XXrem`；
`base.css` 自身 11 处（0.78/0.82/0.88/0.95/1.1 —— 正是被点名要消掉的那档）；圆角只剩 50%/999px（语义正确）。
`--tb-fs-*` 在 base.css 里只用了 3 处（主题格、chip），阶梯主要落在模板层。
`StaticVersion` 20261021a → **20261021b**（主题 css 内容变了，必须换键）。
## 18:2x 提交 test01 删除
`2d13c31` 删掉 `static/css/themes/test01.css` + `static/images/themes/test01/` 两张 webp（用户 18:19 要求）。
`go test ./internal/theme` 仍全绿（测试里的 "test01" 只作 DisplayName 回退样例，不依赖文件）。
⚠️ `static/images/shiroko-cutout.png` 的删除**仍未提交**（属另一件事，docs/theme-shiroko.md 还引用它）。
## 18:2x 删除 shiroko-cutout.png + 清文档引用
用户确认一并删。`docs/theme-shiroko.md` 三处引用改成「参考图不入库」（不再指向具体文件路径）；
顺手修了同页一处过时说法：**「--tb-deco 保持 6 个值」→ 10 个**（槽位早就扩到 10，漏改会让人以为写 6 个就够）。
删除后 embed 无影响（`static/fs.go` 只嵌 `images/themes`，这个文件本来就不参与打包）。
## 18:2x 提交模板令牌化（用户改动，一次性提交）
`001306d`：11 个模板的硬编码字号/圆角换成 `--tb-fs-*` / `--tb-radius*`，工作区已干净。
`TEST_PREVIEW=1 go test ./templates ./internal/i18n` 全绿（顺带刷新了生成器用的快照）。
提交信息里记了 4 处**故意改变观感**的替换，免得以后被当成 regression 查：
explore `.explore-name` 1.2rem→1rem、`.hot-vote-title` 0.98→0.875、首页 `.tb-stat-num` 手机 1.25→1rem、
`.hot-vote-action` 0.82→0.875（变大）。头像 50% / 胶囊 999px 有意保留。
下一轮若要彻底统一：`templates/user/profile.html` 16 处 + `base.css` 自身 11 处；`mail/*` 不要动（邮件客户端不保证 var()）。
## 18:3x 收尾：字号全令牌化 + 主色补到 AA（新增 --tb-on-primary）
**字号**：`templates/user/profile.html` 20 处、`base.css` 9 处全部换成 `--tb-fs-*`。
base.css 里那 4 档导航字号（0.95/0.88/0.82/0.78）合并成「桌面 md → ≤1000 xs」，logo 三档统一 lg。
**保留未改**（有理由）：`.tb-pin-flag` / `.md-body code` 的 `0.9em`（相对父级，换成 rem 会破坏继承）、
验证码的 `1.4rem/1.2rem`（等宽字形尺寸，不是正文阶梯）、chat 关闭按钮 `40px`、`password.html` 的 `3em`、mail/*（邮件客户端不保证 var()）。
行内 `12px` / `0.75rem` 这几处恰好等值，顺手换了；chat 里还剩一个 `13px`（13→12 会缩，没动）。
**主色**（同色相压亮度，目标 4.7 而非 4.5，留余量）：base/screw `#1e87f0`(3.26~3.42) → **`#0e6fd0`**(4.70)，
shiroko `#4a7fc1`(3.69) → **`#3b6dac`**(4.74)，sakura `#e5678f`(2.80) → **`#ba3e66`**(4.70，饱和度压到 .5 保持柔和粉)。
`--tb-primary-weak` 与 shiroko 的两条 box-shadow 一并换 RGB；`TestSwatch` 的断言改成 `#ba3e66`。
⚠️ **主色有两个互相矛盾的角色**：当链接色要「深」，当按钮底色配白字却要「更深的底」——
但深色模式的主色是亮强调（`#5c8dff`/`#ff8ab0`/`#6fa3e0`），白字只有 **2.2~3.1:1**。
所以新增 **`--tb-on-primary`**（亮 `#ffffff` / 暗 `#0b1016`），`.uk-button-primary` 与
`.uk-label:not(danger|warning|success|secondary)` 都吃它 → 深色模式按钮是「浅底深字」。实测 6.10/8.65/7.27。
其它泄漏点：header 验证码 focus 的 `#1e87f0`/`rgba(30,135,240)` → 令牌；profile `.feat-day.is-on` 写死的
`rgba(30,135,240,.14)` → `var(--tb-primary-weak)`；explore 随机投票的 JS outline、vote-results 的行内色 → 令牌。
**深色 muted 之前算漏了**：只对 `--tb-bg` 算（4.7~4.8 以为过了），对**压平后的卡片**才是真实背景
（sakura 4.31 / shiroko 4.17）。已提亮到 `#a18790` / `#7f8ea1`（4.62），base 深色 4.77 本来就过。
**生成器**：`paletteVars` 增加 `--tb-on-primary`（白字/深字里挑更优）；`?dump=palette` 增加
`onPrimaryCr` / `onPrimaryPickedBest` / `warnings` —— 主色卡在中间调时**不断言失败**（那是主色要调，
不是挑错），列进 warnings；配色面板给橙色提示「压深配白字 / 提亮配深字」。
`_scaffold.css` 令牌数 29 → 30。`StaticVersion` → **`20261021c`**。
最终审计 8 种组合（base 亮暗 + 三主题亮暗）全部 ≥4.5。⚠️ 写 CSS 用 python 改时注意：`git checkout` 会把
base.css 还原成 CRLF，插入行要用同一行尾，否则变 MIXED。
## 18:5x 检查测试环境部署 → 抓到设置页色块 ZgotmplZ
**部署核对（都对）**：`base.css?v=20261021c`、三份 CSS（base/sakura/shiroko）与本地**逐字节一致**；
设置页主题列表 = 跟随站点默认 / 基础外观 / 樱花 / 砂狼白子，**test01 已消失**、名称无 `theme.name.*` key；
登录按钮是新蓝（#0e6fd0）白字，箱主页排版正常。
⚠️ **admin6 的主题被重置成「跟随站点默认」**（它原来选的是已删除的 test01）→ 箱主页 `<html>` 没有
`data-theme-style`，现在是基础外观。要验证主题得重新选 sakura/shiroko。
**P1 缺陷（既有，非本次改动引入）**：设置页四个主题色块全是 `style="background: ZgotmplZ"`。
`html/template` 会对 `style` 属性做 CSS 过滤，未标记安全的 `linear-gradient(...)` 一律替换成 ZgotmplZ。
`swatchOf` 一直在生成渐变串，所以这个色块**从来没显示过**。
修法：FuncMap 加 `safeCSS` → `template.CSS`，模板 `{{ safeCSS .Swatch }}`（值只来自 swatchOf，不接受用户输入）。
加了 `TestThemeSwatchRenders`（渲染 user/profile，断言不含 ZgotmplZ 且含渐变串），并做变异验证：
把 `safeCSS` 去掉 → 测试如期 FAIL。
⚠️ 教训：任何 `style="..."` 里塞模板值都要过一遍这个过滤器；模板名在测试里**不带 `.html`**（`user/profile`）。
## 19:0x 复检部署：色块修复已上线 + 主题链路验证
`1f29d3e` 部署后复检，**全部通过**：
- 设置页 HTML 里 `ZgotmplZ` 计数 **0**，四个 `tb-theme-swatch` 都是真渐变
（跟随默认灰斜块 / `#f7f8fa→#0e6fd0` / `#fceef3→#ba3e66` / `#eef3f9→#3b6dac`），截图确认有色块。
- 主题链路：把 admin6 的 `theme` 设为 `shiroko`（`POST /user/profile/theme`，该表单只有 `_csrf`+`theme`
两个字段，单独提交安全），随后
`/_/admin6` → `data-page-scope="box"`、`/_/admin6/95` → `question`、
`/user/questions` → `admin`、`/user/profile` → `profile`，四处都带 `data-theme-style="shiroko"`
与 `themes/shiroko.css?v=20261021c`。桌面渲染正常（人物站地面、车与人同向、光环完整、卡片磨砂）。
- ⚠️ **admin6 现在选着 shiroko**（为验证链路设的），要还原就把主题改回「跟随站点默认」。
- ⚠️ **`--window-size=390,844` 得到的不是 390 CSS 视口**：同一参数截本地快照也会「右侧被切」，
真实排版没问题 —— 移动端必须用**宽度锁定的 iframe**（生成器那套）验，别据 window-size 结论判 bug。
shiroko 的窄屏块（≤900px）只有一条 `html[data-theme-style]`(0,1,1)，但它没有任何
`[data-page-scope]` 块，所以不会被压住；深色块的 `--tb-page-image` 覆盖窄屏属预期（深色不用实景照）。
## 19:2x shiroko 单车/步枪「白色没抠」→ 白上白，只能全白转透明
**根因不是抠图参数**：素材是「白底 + 白车架」。采样确认车架涂装与背景白是同一个值
（都在 `#f9f9f9`，差 0~3 级），颜色上完全分不开；四角 floodfill 只吃掉外圈，
轮圈内、车架三角、车筐、枪与车架之间的白整块留着 → 看着像没抠。
量化：修复前**不透明像素里近白(>240) 占 50%**，全透明只有 43%。
试过三种程序化方案（都写了脚本）：
1. 只按「近白厚度」区分白洞/白涂装（腐蚀测厚度）→ **失败**：轮辐间的扇形白楔宽 9~13px，
与车架管 5~10px 重叠，阈值怎么调都会留下白色楔子（更难看）。
2. 全白转透明（`min(r,g,b)≥238` 软过渡 + 饱和度>14 保留彩色）→ 采用。成果：
不透明率 19.4%、近白 0.0%、29KB；轮辐/车架/车筐全成描边，粉色轮圈 + 蓝枪托 + 阴影仍在。
3. 手绘 SVG 替换：未做（不如现成素材真实）。
**代价要记住**：车身填色一起没了，成品是**线稿风**，在 1512 整页里偏淡（远看像铅笔稿）。
若用户要「实心车」，唯一正解是重出一张**绿幕/透明背景 + 车身用浅灰蓝等中间调**的素材
（白车在浅场景里本来就发飘），已写进 docs/theme-shiroko-assets-spec.md 的「白上白」小节，
验收清单也加了「不透明像素近白占比应≈0」这条。
改动：`props/bike.webp`（397×259 画布不变，位置公式不用动）、css 里图片 `?v=20261020d→20261021a`、
`StaticVersion 20261021c→20261021d`、两份 docs 同步。`go test ./internal/theme` 全绿。
⚠️ 画布尺寸**不能裁**：裁完 `auto 259px` 的显示宽度变了，`left calc(50% - 612px)` 的锚点会跟着漂。
## 19:4x 两件事：/user/questions「卡片透明」根因 + 主题素材上 R2
**1) /user/questions 卡片透明 —— 不是主题，是模板没有卡片**
`templates/user/question-list.html` 整个文件只有 1 处 `.uk-card`（投票 tab 的「我的投票」标题条）；
提问列表是 `<div class="uk-margin-medium-bottom">` + `<hr>` **裸铺在页面上**。
默认主题底色 #fff 看不出来，换带整页插画的主题后场景整片透上来 = 「卡片透明」。
修：`.qlist-panel` 加卡片底（`--tb-surface` + `--tb-radius` + `--tb-shadow` + padding，
≤640px 收紧），内部那张 `.uk-card-default` 降成 `--tb-surface-2` 去阴影（防卡片套卡片）。
验证：本地快照注入 shiroko 后，行内容落在卡上，场景只从卡外透出；默认外观只是多一层白卡。
⚠️ 页面级样式仍写在模板 `<style>` 里（不搬 base.css），符合既有约定。
**2) 主题素材放 R2 —— 三种做法，生成器已支持 A**
素材只有一处引用：主题 css 的 `url()`（分享卡是 Go 用 imaging 画的，不读素材）。
- A 生成器「素材前缀」：导出面板新增输入（`S.assetBase`，存进工程 json，`?assetbase=` 可测），
`urlOf()` 一处决定地址 → 绝对 URL。**踩到过坑：`layerCSS` 里复制了一份路径拼接**，
只改 urlOf 会导致「背景走 CDN、装饰还指本地」，已统一到 urlOf。
- B 应用内 301：`[theme] asset_base` + 中间件（必须注册在 `flamego.Static` **之前**）。
- C 边缘/反代改写（CF Origin Rule / nginx）。
细节与取舍写进新文档 `docs/theme-assets-cdn.md`（含缓存、CORS、深色无素材、迁移 sed 命令）。
⚠️ UI 坑：面板 240px 里 4 个中文字的 label 会被 flex 压缩、末字被输入框切掉 →
label 要 `flex:0 0 auto; white-space:nowrap`，宽度给 84px 才够（68px 仍会切）。
**3) 素材托管：本地 / 任意 S3 兼容，生成器内测通即可上传**
用户要求「放本地还是放 S3 兼容（不只 R2）由部署者自己定，并且能配好即测、测通即传」。
- `serve.py` 手写 SigV4（零依赖，PUT/GET/DELETE/HEAD），新增 `/api/s3/ping|test|upload`。
测试连接四步：HEAD 桶 → PUT 探针 → GET 读回比对 → 匿名 GET（能否被浏览器直读）→ 删探针。
4xx 把 `<Code>` 翻成人话（`S3_HINTS`），签名失败直接指向密钥/Region/时钟三件事。
- `index.html` 新增「素材托管」面板，上传集合复用导出用的 `usedAssetIds()`；
成功后自动回填「素材前缀」。密钥只进 sessionStorage，不进工程 json（有断言）。
- **两个真 bug**：①`usedAssetIds()` 返回 Set，`!ids.length` 恒真 → 永远「还没有素材」；
②字段填完 700ms 内刷新会丢（scheduleSave 防抖）→ 失焦/切模式/上传成功时立即 `saveDraft()`。
- **验证手段**：`check_sigv4.py` 用 aws-sdk-go-v2 的 signer 逐字节对拍（6/6）——
裸 SignHTTP 会二次转义 URI、而 S3 client 关了它，所以用例只用 ASCII，
中文 key 的编码规则跟随 S3 client（单次 RFC3986）。
`selftest_upload.py` 假 S3 跑 16 项；`mock_s3.py` 可手动点面板。
- ⚠️ **8777 端口陷阱**：Windows `SO_REUSEADDR` 让新进程 bind 成功却抢不到 accept，
症状是「代码改了但接口还是 404」。查 `Get-NetTCPConnection -LocalPort 8777`，或换端口验证。
**4) 远端素材检测与管理（用户「还没测，想先看到 S3 上有什么」）**
- serve.py：`s3_request` 支持 query，新增 `list_objects`（ListObjectsV2 + 分页）与
`delete_objects`；端点 `/api/s3/list`、`/api/s3/delete`。
- index.html：远端素材区，按对象键名跟本地比 → 一致 / 旧图（同名大小不同）/ 多余 / 缺失；
「补齐差异」只传缺的与旧图，「删除多余」批量删，单行 ↻ 覆盖、✕ 删除。
- ⚠️ **键的两种形态**：list 返回**完整键**（含 `<路径前缀>/`），upload/delete 接口收
**相对键**。不剥这一层，服务端会再拼一次前缀 → 删一个不存在的键，S3 还回 204，
表现为「显示删除成功但东西还在」。加 `relKey()` 统一转换。
- ⚠️ `check_sigv4.py` 补了带 query 的用例（ListObjectsV2 三参数、乱序传入的分页 token），
8/8 一致 —— canonical query 的排序与百分号编码也必须对拍，漏测会静默失效。
**5) 生成器默认监听 0.0.0.0（局域网/手机可用）**
- `serve.py --host` 默认由 127.0.0.1 改成 0.0.0.0；启动时用 `local_addresses()` 列出所有
网卡 IP（getaddrinfo + UDP connect 双路兜底），0.0.0.0 本身不打印成可点地址。
- 顺带修两个真问题：①`TCPServer` 是单线程 —— 传一张几 MB 的图会卡住 iframe 预览与其它请求，
换 `ThreadingTCPServer`；②写接口加 `_same_origin()`（Origin 与 Host 比对，无 Origin 放行），
挡住「同网段另一个网页借访客浏览器发写请求」。curl/脚本不受影响。
- `index.html` 提示文案里写死的 `127.0.0.1:8777` 改成 `HERE`（`location.host`）——
用局域网 IP 打开时不能反过来告诉用户「请用 127.0.0.1 打开」。
- ⚠️ **浏览器按 origin 隔离存储**：`127.0.0.1` 与 `192.168.x.x` 是两个站点，
localStorage 草稿与 sessionStorage 里的 S3 密钥不共享，换地址要重填一次（README 已写）。
- `mock_s3.py` 加 `--host`（默认仍 127.0.0.1）：生成器在别的设备上打开时，假 S3 也要 0.0.0.0。
- 验证：局域网 IP 访问 200、`--host 127.0.0.1` 时局域网访问连不上、跨站 Origin 被拒（403）、
局域网 origin 下检测/补齐全走通。⚠️ 本机 curl 访问 192.168.x.x 必须加 `--noproxy '*'`，
否则被系统代理接走报 502。
.workbuddy/memory/2026-10-23.md
-250
View File
@@ -1,250 +0,0 @@
# 2026-10-23
## 单题分享卡二维码提到 5px/模块（`310f851`）
用户决定「单题一起做」，同时否掉方案 5（结果落盘/R2）——理由：功能使用率不高，不值得大动干戈。
- 单题卡卡片 210×255 放不下 5px 模块（37 模块要 185px）：`QQRCardW` 236、`QQRCardH` 300、
`QQRSize` 190。X 由 `QContentX+QContentW-QQRCardW` 派生 → 679，Y 居中 → 120。
- `QTextMaxW` / `qLeftClip` 都从 `QQRCardX` 派生，左栏自动收窄 26px，无需另改。
- 抽了 `drawQuestionQRCard(canvas, user, question, logo, fontCtx)`（handler 只剩调用），
这样测试能直接渲染整卡：`TestQuestionQRCardLayout` 断言正方形 / 模块≥5 / 四边留白≥20 /
居中≤1px，`TEST_PREVIEW=1` 出 `outputs/sharecard-preview/question-card.png`。
- 实测：二维码 185px、居中偏差 0.5px、上下留白 34px；gozxing 在 960/720/480/320 全通过。
变异验证：`QQRSize` 改回 150 → "QR module is 4px, want >=5" FAIL。
- 未做（用户明确不要）：分享卡结果落盘/上 R2。进程内 LRU 仍是 16 条 + TTL 1h，
冷渲染成本接受现状。
## 部署后复验（箱子卡 + 单题卡，`310f851`）
- 箱子卡：QR 185×185 @ y120-304 / x702-886，卡中心 795 → 着墨中心 794.0（−1.0px）；
提示语 794.0、分隔线 795.0、链接两行 795.0 / 794.5；上下留白各 18px。
- 单题卡：QR 185×185 @ y154-338 / x704-888，卡中心 797 → 着墨中心 796.0（−1.0px）；
提示语 797.0；上下留白 34 / 33px。
- 端到端解码（部署图，含真实背景与内嵌头像）：两张卡在 960 / 720 / 480 / 320 宽全部 OK，
内容正确（单题卡 `/114`）。
- 顺带确认 **不是** bug：删除提问后分享卡立刻 302（`GetByID` 在缓存查询之前），
不存在「删了还能靠缓存取到图」的窗口。
## 缓存 key 排查结论（`675cecb`）
用户要求「有影响就修」。查下来**当前没有实际影响**，只有一条理论缺口：
| 可能场景 | 是否真有影响 | 原因 |
|---|---|---|
| 用户改域名 → 二维码指向旧域名 | ❌ 当前无 | Domain 只在注册时写（`register.go` / `CreateUser`），无改域名入口 |
| 改 ExternalURL / ShareBackground | ❌ 无 | 配置需重启，缓存是进程内的，重启即清 |
| 换头像/背景后仍是旧图 | ❌ 无 | R2 key = `picture/日期/随机 hex`，内容不可变，换图必换 URL |
| 域名将来可改 | ⚠️ 理论 | 单题卡 key 未含 `user.Domain` |
处理：给 `questionShareCardCacheKey` 补 `user.Domain`（箱子卡本来就有）；
两处「TTL 30 分钟」注释改成 1 小时（代码一直是 `time.Hour`）。
新增 `TestShareCardCacheKeysCoverDrawnFields`——逐字段变异断言 key 必须变，
去掉 Domain 立刻 FAIL。**以后改分享卡要加新字段时，先看这张测试。**
## 正式环境「蜜罐封了但还能访问」排查（IPv6）
本地用 IPv6 全程复现了一遍 autoban 链路（CF-Connecting-IP 注入 + trust_proxy=true）：
封禁前 200 → POST 凭据后 `IsBanned`=true → 同地址 403 → 同 /64 换地址仍 403 →
不同 /64 放行 200。**判定逻辑与中间件都正确，不是代码 bug。**
封禁键 = `shared.LimitKey(ResolveClientIP(req))`：
- IPv4 原样
- IPv6 折成 `xxxx:xxxx:xxxx:xxxx::/64`
写入（honeypot.Serve / route.NotFound）与检查（autobanMiddleware）用的是同一个函数，一致。
⇒ 「邮件说封了但能访问」只能是**键不一致**或**进程重启（封禁纯内存态）**。
三种可能：① 部署后重启过；② trust_proxy 未配 → 键是反代地址（`127.0.0.1` / `::/64`）；
③ 前后请求地址族或 /64 不同（双栈、IPv6 前缀轮换、多实例）。
判定方法：`honeypot hits` / `data/honeypot-creds/creds-YYYY-MM-DD.jsonl` 里的 `ip` 字段
就是**被封的键**，与本机 `curl -6 ifconfig.co` 比对即可。
**发现的真实取证缺陷**：`db.HoneypotHit.IP` 与 creds 文件存的是折叠后的 `/64` 键，
IPv6 丢掉了精确地址（IPv4 无损）；邮件里也只给键，运维会误以为「这不是我的 IP」。
建议：取证记精确 IP，封禁仍用 /64；建封与 403 命中各打一条日志。
### 据此动手改的三处（精确 IP / 封禁键分离 + 可观测性）
1. `honeypotHandler.Serve` 拆两个变量：`clientIP = ResolveClientIP`（精确，取证/邮件用）、
`banKey = LimitKey(clientIP)`（/64，封禁/采样/告警去重用）。DB 与凭据文件都写 clientIP。
2. `autoban.Options.OnBan(key, duration, reason)` 回调（新增 `ReasonProbe` / `ReasonHoneypot`），
保持 autoban 纯标准库、不再依赖 logrus。route.newBanner 注入 → 建封打 WARN
（ban_key / reason / duration / expires_at）。中间件 403 分支打 Debug。
3. 邮件同时给「来源 IP」（精确）与「封禁范围」（ban_key，仅 `ne .ip .ban_key` 时渲染）；
顺手把模板里过时的「已入库」改成「写入取证文件」（上一轮凭据外置后没同步）。
副作用修掉：`honeypot stats` 的来源排行改按 `LimitKey` 合并（否则 IPv6 轮换地址会把排行碎成
几十条各 1 次）。SQL 取 `limit*4` 再合并，属近似。
测试：`TestHoneypotRecordsExactIPv6ButBansByPrefix`（精确 IP + /64 键 + store 断言）、
`TestOnBanCallback`、`TestHoneypotAlertTemplateRenders`、`TestMergeSourcesByKey`。
四处变异验证有效（改回存聚合键 / 封禁用精确地址 / 去掉 notifyBan / 不合并排行）。
**变异验证的坑**：把 `shared.LimitKey(r.IP)` 改成 `r.IP` 会因 `shared` 未使用而
**编译失败**（不是断言失败）；变异要保证仍能编译（改成 `LimitKey(r.IP) + r.IP` 才测到逻辑）。
### 测试环境验收（部署 29ddee0 后）
伪造 `CF-Connecting-IP: 2001:db8:…`（RFC 文档保留段，封了不影响任何人）直连源站端口：
- 基线 200 → POST 凭据 200（假页面）→ **同 /64 换地址 403**（聚合封禁生效）；
- 凭据文件 `ip` = `2001:db8:dead:beef::1234`（精确，无 /64 后缀），`banned:true`；
- 换另一个 /64（`2001:db8:cafe::1`）→ 200，说明封的是 /64 不是全局；
- `od -c` 复核 `"path":"/wp-login.php"` **无前导空格** → cleanPath 生效。
**教训**：上一次那条 `" /wp-login.php"` 是**那次请求的 URI 本身带空格**（本地实测
`Match(" /wp-login.php")=true` 靠 TrimSpace 命中、`Match("/ wp-login.php")=false`），
不是代码问题；判断这类"看不见的字符"一律用 `od -c`，别靠终端渲染。
测试环境服务是**前台跑在 /dev/pts/1**，日志不在文件里 —— 拿日志要 `tmux capture-pane` 或
下次启动加 `>> logs/tamabox.log 2>&1`。
### 蜜罐升级为 9 个伪装家族
新增 `family.go`（皮肤表）/ `asset.go`（静态资源占位）/ 重写 `page.go`：
- 按路径分发：wordpress / phpmyadmin / tomcat(401+Basic) / jenkins / grafana / gitlab /
luci / joomla / generic；每类独立字段名、配色、指纹响应头、Set-Cookie；
- `credentialKeys` 扩 `pma_*` / `j_*` / `luci_*` / `user[login]`；
`token` 只用于判 HadFields，**不进 isPasswordKey**（否则 PMA 的 hidden token 会随机顶掉真密码）；
- 静态资源（`/wp-admin/css/…` 等）回占位内容，**不落库不计数** —— 一次页面加载 5–10 个请求；
- `honeypot paths` 加家族汇总（实测 110 条：generic 84 / wordpress 10 / tomcat 6 / gitlab 3 / pma 3 …）；
- 性能：RenderFamily 12µs→3.7µs、22→2 allocs、19.5KB→5.2KB（禁 `"a"+b+"c"`、Replacer 提包级）。
**新工具** `dev/preview-honeypot`：渲染 9 个家族到 `outputs/honeypot-preview/index.html`，
配 chrome headless 截图核对外观。靠它发现两处「源码看不出、截图一眼假」：
Tomcat 的 skin 忘了 css（按钮白字无底色）、WP 登录页底部挂着 404 文案。
### 测试环境验收：9 家族伪装（部署 7225f68 后，只读 GET）
全部符合预期：8 个家族 title/generator 各不相同、Tomcat 401+Basic realm、
静态资源 200 且 MIME 正确（128B css / 81B js / 70B png）、插件目录 .php 回 404、
业务路由（/login /user /static /api）无 canary、界外路径仍 302 → /。
发现的漏洞（按优先级）：
1. **P1 `/xmlrpc.php` 回 HTML 登录页** —— 而我们自己发了 `X-Pingback: /xmlrpc.php`，
真实 WP 回 text/xml，等于自己指给自己一个明显假的地址；同时丢掉 WP 爆破最有价值的
捕获通道（xmlrpc system.multicall 一次可试上千组，绕开登录限速）。
2. **P2 每次请求恒定值**：PMA `token=e1a4c0b7d2f58g93`（还带非 hex 的 g）、
generic `csrf_token=a7f3c1e9b2d4`、`X-Jenkins-Session: 8b1f2c4d`。
两次请求完全相同 → 跨请求指纹即可识别。应改每请求随机。
3. **P2 `X-Pingback` 用相对路径**，真实 WP 给绝对 URL。
4. **P3 `/phpinfo.php` 漏匹配**：路径清单里是 `/phpinfo`、`/info.php` 精确项，
段前缀匹配不覆盖 `.php` 变体 → 302。可加「p 去掉 .php 后在集合内」的兜底。
5. **P3 `/wp-json/wp/v2/users` 回 HTML**，真实 WP 回 JSON（用户枚举接口）。
6. P3 `X-Frame-Options: DENY` / `Cache-Control: no-store` 与真实 WP 不同，
但属全局中间件，改动影响全站。
### 修 P1/P2：XML-RPC 端点 + 动态 token + .php 兜底
- 新增 `internal/security/honeypot/xmlrpc.go`：`/xmlrpc.php` 不再回登录页。
GET→405+XML fault「XML-RPC services are disabled」；POST methodCall→200+fault
「Incorrect username or password」；POST system.listMethods→方法列表模板。
凭据提取用正则（不上 encoding/xml，蜜罐高频命中）：抓 `<string>`、剔除
methodName 与 http(s) URL、两两配对；`blog_id=1` 这种「奇数长度+首项短数字」
会丢首项纠正错位；第一组进标准字段，其余进 `cred2.*`，原始串全量进 `xmlrpc.N`
（配置上限 16 对 / raw 8KB）。
- 动态占位符：`LoginPageVars.Nonce`（32 hex，`math/rand/v2`，刻意不用 crypto/rand，
这些是假 token 只需「每次不同」）。支持 `$hex8/16/32` 与 `$base`；
页头、hidden、Set-Cookie 共用同一套 nonce。
- `X-Pingback` 改绝对地址（`$base/xmlrpc.php`），没配 `external_url` 就不发。
- `Cache-Control` 从 `no-store` 改 `no-cache, must-revalidate, max-age=0`（更像 WP/PMA）。
- Grafana/GitLab 补真实会种的会话 cookie（`grafana_sess`、`_gitlab_session`，动态）。
- `Match` 增加 `.php` 变体兜底：`/phpinfo.php` 之前漏匹配 → 302。
- 性能：RenderFamily 3.7µs→4.18µs、2→3 allocs（多的一次是 hex 编码），可接受。
四处变异验证有效（固定 token / xmlrpc 分支失效 / Pingback 相对路径 / .php 兜底失效）。
### 测试环境验收：XML-RPC 端点（部署 9d3f5a7 后）
- `GET /xmlrpc.php` → **405 + text/xml**（与真实 WP 一致，XML-RPC 只接受 POST），
用户误以为这是报错；405 的 body 是 `<fault>XML-RPC services are disabled…`。
- `POST system.listMethods` → 200 + 方法列表 ✓。
- `POST wp.getUsersBlogs`（伪造 `CF-Connecting-IP: 2001:db8:beef::7`）→ 凭据落文件：
`username=xruser / password=xrpass`、`fields.xmlrpc.0/1`、`xmlrpc.method`、`banned:true` ✓。
- 紧接的下一次请求 `403 Forbidden` = 已封禁（第一次 POST 就封了该 /64），属预期。
- 动态 token 两次不同（`d85a8c…` / `76a404…`）✓。
**再次出现的 `"path":" /xmlrpc.php"` 已判定为粘贴/终端产物**：`IsXMLRPCPath` 不做 trim，
若 `path` 真带前导空格根本进不了 XML-RPC 分支，而记录里有 `xmlrpc.*` 字段 ⇒ 落盘值必是
`/xmlrpc.php`。这类"看不见的字符"结论一律靠 `od -c`，别靠终端回显。
### 403 响应体换成图片
用户给了 R2 预签名链接（`X-Amz-Expires=604800`，7 天后失效）——**不能直接热链**。
下载后（256×256 webp，8.6 KB）用 `//go:embed` 编进二进制：
`internal/route/assets/403.webp` + `internal/route/banned.go: writeBanned()`。
- 状态码仍是 403（语义不变），只换 body；`Content-Type: image/webp` + 显式 `Content-Length`
（8 KB 超过 Go 的 2 KB 缓冲，不设会退回 chunked）+ `no-store`；HEAD 不写 body。
- 放在 `internal/route/assets/` 而不是 `static/`：static 会多出一个可公开访问的 URL。
- 换图方式：覆盖同目录 403.webp → 重新编译，无配置项。
- 体积代价：每封禁请求 8.6 KB（原 13 字节）。被封来源重试频繁时要留意带宽，
已压到 256×256；别塞几百 KB 原图。
### 关于「403 图放 R2 是否更好」的结论
结论：**保持 embed**。关键事实是「服务端代理/重定向并不省我们带宽」——
字节最终还是从本机发给被封客户端；想真省只能让客户端自己去 R2 取，
那就要放弃「403 直接是图片」，改成 403 + 一个 `<img src=外链>` 的 HTML。
而本项目 R2 目前只有预签名 URL（7 天过期），长期用必须开 r2.dev 或绑自定义域
（docs/theme-new-sakura.md 已记：直连 `*.r2.cloudflarestorage.com` 会 403）。
8.6 KB 的单张图不值得引入外部依赖；被 ban 的多是脚本，根本不会加载图片。
若动机只是「换图不想重编译」，加 `[security] ban_image_path` 磁盘覆盖更划算。
### 改为 ban_image_path（配置驱动，默认纯文字）
按用户要求撤掉 embed：`internal/route/assets/`（含 403.webp）已删除，
行为改为「配了合法图 → 回图；留空 / 读不到 / 不是图 / >2MB → 纯文字 403」。
- `[security] ban_image_path`（相对路径以进程工作目录为基准）；
- `loadBanImage()` 在 `route.New()` 里启动时读一次 → `atomic.Pointer[banResponse]`，
热路径零磁盘 IO；任何失败只 Warn 不改启动（封禁响应是最后一道兜底，不能变 500）；
- **只认内容不认扩展名**（`http.DetectContentType` 必须是 `image/*`）：配成
app.ini/.env 会被拒绝，否则等于把配置文件吐给攻击者（变异验证过这条）；
- 上限 2 MB（被封来源反复重试，大图放大出网带宽）；`Content-Length` 显式给；
HEAD 不写 body；`no-store`。
- 实测 sniff：真 webp → `image/webp`；`app.sample.ini` → `text/plain`（被拒）。
**教训**：同一功能改了两版（先 embed 后配置化），第二版要把上一版的资源一起清掉，
否则留一个没人引用的 `assets` 包。`go vet ./...` 不报、测试也不报（该包仍被旧测试引用时）。
## /user/questions：筛选项「已读 是/否」+ 手机端标签行不折行
- 筛选栏第 5 列标签「阅读状态」四字，在 ~53px 的窄列里必折两行。
→ 词条 `qlist.readStatus` 删除，换 `qlist.readFilter`（已读/Read/既読/已讀）+
`qlist.filterYes`/`qlist.filterNo`（是/否）。**只改标签，option 的 value 仍是
read/unread**（后端 `readParam` 校验依赖它）。`qlist.all`（全部）保留作默认不筛选。
- 手机端「时间 + 状态标签 + 标记/置顶」挤一行：实测（360/390/375 iframe + dump-dom 量 rect）
一行只有 306–336px，完整时间占 127px，2 标签 + 2 按钮要 343px → 必折。
→ 时间改 `tb-short`=m-d H:i / `tb-text`=Y-m-d H:i:s（复用 pill 的 640px 断点）；
→ `.qlist-pill` 基础值 min-width 40→34、padding 0 8→6（手机端省 20px），
桌面 `@media(min-width:640px)` 仍覆盖回 62px/10px。
结果：2 标签 + 2 按钮在 360 就单行；「私密+待答+未读」三标签仍会在 ≤375 折行（可接受）。
- 量手机宽度别用 `chrome --window-size=360`：Windows headless=old 有 ~500px 最小窗宽，
实测 innerWidth 恒为 500。用 360px 宽 iframe + `--allow-file-access-from-files`，
结果由 iframe 里 `window.top.document.title` 带回，`--dump-dom` 读。
### 手机端时间的年份：逐条补年，不做按年分组（DateCompact）
- `Template.FuncMap` 新增 `DateCompact`（内部 `dateCompact(t, now)`）：同年 → `01-02 15:04`，
跨年 → `2006-01-02 15:04`。桌面端仍走 `tb-text` 的完整格式，不受影响。
- 用户问过「省了年要不要按年把问题隔开」——**不做**。理由是列表带游标分页（`*_cursor`）+ 可切
排序 + 4 个筛选 + 关键词搜索：组标题只按当前页算，翻页会重复出现同一年标题；换了排序
（最早→最新）或搜索时又会出现空组/错位。逐条补年份零结构成本、无耦合。
真要年份维度，顺序应是：①跨年补年（已做）②筛选栏加「年份」下拉（distinct year，走 SQL）。
- 实测（360 宽 306px）：跨年格式占 109px（vs 同年 73px）。跨年 + 2 标签 + 2 按钮 = 309px，
差 3px 会在 360 宽折行；390 及以上的 2 标签组合都单行。预览数据里放了一条 2025 年条目用于核对。
## 全站数据页 /stats（替换首页统计卡）
- 首页底部「站点统计」三行小卡 → 换成一行摘要 + 入口按钮；完整数据在新公开页 `/stats`。
明细见 `topics/stats.md`。
- 新增：`internal/db/analytics.go`（聚合 SQL，方言收敛）、`internal/stats/overview.go`
（自然日缓存 + 补齐空日期）、`internal/stats/page.go`（i18n 标签 + 洞察文案）、
`route/stats.go`、`templates/stats.html`、`internal/template/chart.go`（折线坐标等 5 个函数）。
- 图表零依赖：折线 SVG，柱状/分布条用百分比高度，环形用 `pathLength=100` 的 dasharray，
热力图 CSS grid + 主色 opacity 分 4 档。
- 口径修正：环比改成「上月 vs 上上月」（本月残月比整月会在每月 1 号算出 -95%）。
- 补索引 `questions(created_at)`；启动后 3s 异步预热当天快照。
- 测试：`internal/db/analytics_test.go` 连真库验证（软删除不计入、分桶下标、DOW 对齐）、
`internal/stats/overview_test.go`（补齐日期、月底不溢出、除零）。全绿。
- 踩坑：预览页 base.css 用 `href="/static/..."` 绝对路径，file:// 下取不到 →
令牌全缺、图表全透明。`writePreview` 已改成同时重写 `href="/static/`。
.workbuddy/memory/2026-10-24.md
-144
View File
@@ -1,144 +0,0 @@
# 2026-10-24
## /stats 入口收敛到页脚
- 用户要求：首页那张统计入口卡取消，入口只放页脚「社区规则」与「找站长」之间。
- 改动：
- `templates/home.html`：删掉统计入口卡整块 + `.tb-stats-entry*` 样式（原 `</details>` 后那一段）。
- `route/home.go`：`Home` 不再调 `stats.Get`（模板已不读 `.SiteStats`），去掉 `logrus` import；
`/api/v1/site-stats` 与 `SiteStatsAPI` 保留未动。
- 四份 i18n 字典删掉已无引用的 `site.stats.open`（`site.stats` 老词条保留）。
- 页脚 `templates/base/footer.html` 的 `site.footer.stats` 位置本就在 rules 与 admin 之间，无需再动。
- 验证：`go build` + `./internal/i18n` / `./templates` / `./route/...` 测试全绿；gofmt 无差异；
重新生成预览确认首页无 `tb-stats-entry`，页脚渲染为「社区规则 | 数据 | 找站长」。
- 教训：删掉页面唯一消费方后，服务端的取数调用（`stats.Get`）要同步删，
否则每次访问首页白算一次快照；对应 i18n 词条也要一起清，避免留死条目。
## /stats 文案与脚注排版修正
- 页脚入口文案「数据」→「统计数据」（`site.footer.stats`，四语言 `Statistics` / `統計データ` / `統計數據`）。
- **「提问最集中在三 19 点前后」的 bug**：洞察句子复用了热力图列头的 `stats.wd.*`
（"一"…"日" / "Mon"…），那是为窄列头设计的单字标签，进句子就成了"三"、英文是 "Wed"。
新增一组完整名 `stats.weekday.1..7`（周一/週一/Monday/月曜日），洞察改用这组；
`stats.wd.*` 只留给热力图列头。已在 `overview_test.go` 加断言锁住，防止回退。
→ 教训：**短标签和完整名必须分两套词条**，别为了少写一组 key 复用。
- 页面脚注四条时间（基准日 / 计算于 / 最后一条提问 / 最后一条回答）由
「A：x · B：y」挤成一行改为 `grid-template-columns: max-content 1fr` 各占一行，
标签列与值列对齐；下面两段说明仍为独立段落。四个标签统一带冒号。
## 部署前自查：两个 P0 都已修
用户部署到测试环境后要求自查。查出的问题都是我自己上一轮引入的：
1. **「今日」两项被每日缓存冻住**（P0，与页面「实时」说明矛盾）。
→ `TodayCounts` 拆出，60 秒 TTL + 跨日按日期失效；命中缓存时返回副本。
新增 `TestTodayNumbersNotFrozen` / `TestTodayCacheExpiresAcrossMidnight`。
2. **日期分组跟着 PG 会话时区（默认 UTC）**（P0，隐蔽：数字都"合理"，只是整体偏 8 小时）。
psql 实测：`2026-10-24 01:30+08` 在 UTC 会话下 to_char 得 `2026-10-23`、hour=17。
→ `analyticsLocalize()` 用 `AT TIME ZONE INTERVAL '+08:00'`（偏移取 `time.At()` 的 Zone，
不用 IANA 名）。EXPLAIN 确认过滤仍走 created_at 索引。
3. PeakDay 用 `>=` 会让「最忙的一天」随更新漂移到最近的同值日期 → 改 `>`。
4. `ovRefresh` 里的聚合改用 `context.WithoutCancel` + 30s 超时：第一个访客中途关页面时，
排队的请求不会各自重跑全表 GROUP BY。
性能实测（20 万行）：totals 337ms / 字数分布 313ms / 热力图 100ms / 日趋势 47ms，
本地合计约 0.8s，1C1G 估 2s，靠预热兜住。百万行才需要合并扫描。
顺带发现（未改，与本次无关）：`Dockerfile` 基础镜像是 `golang:1.20-alpine`，
而 `go.mod` 要求 `go 1.27.3` —— 1.20 不支持 GOTOOLCHAIN 自动下载，Docker 构建必然失败；
`-X` 里的包路径还是 `NekoWheel/NekoBox`。说明实际部署不走这个 Dockerfile。
## 测试环境实测（box-dev-api.337845818.best，用户时区 UTC+8）
- `/stats` 200，首访 5.2s（含 TLS），稳定后 TTFB 1.6s，同站 `/rules` 1.34s
→ 本页只多约 250ms，1C1G 上可接受，无需合并聚合 SQL。
- 环境默认语言是 ja（`/`、`/rules` 同样是 ja），与本次改动无关；语言存 session
（`/i18n/{lang}`），故 /stats **绝不能加 CDN 缓存头** —— 内容随 session 变化且无 Vary: Cookie。
- 逐项验算自洽：月柱合计 95 = 累计提问；热力图 7×24=168 格合计 95；
最忙时段周三 19 点 = 22 与小时合计 26 峰值一致；折线 30 点峰值 10-19 共 5 条。
- `/stats/` 尾斜杠 302 跳首页 —— 与 `/rules/`、`/sponsor/` 一致，框架行为。
## P0：回答耗时口径是错的（本次修）
`SetRead` 把 updated_at 往前推（实测 10 天前的提问，delta = 240h）。
所以「回答耗时 = updated_at − created_at」实际测的是「提问到最后一次被碰」，
线上「6 条超过 7 天」就是这么来的，24 小时占比 66.7% 同样偏低。
修法：`questions.answered_at`（首次回答时间），只在 answer 由空变非空时写，
改写回答不重置；聚合 `COALESCE(answered_at, updated_at)`；加列时回填一次冻结历史。
测试：`internal/db/answered_at_test.go` 5 个用例，含变异验证（改回 updated_at 即红）。
## 顺带修
- 环比句式：中文「比前一个月 -69.6%」、英文「...: -69.6% questions.」读不通 →
「上月提问量环比 %s%%」/「Month-over-month change for last month: %s%%」。
- 脚注「当日 0 点的快照」不实（实际是当天首访/重启时算）→ 改成准确描述。
- DB 故障时 `ovRefresh` 串行 + 30s 超时会让请求排成 N×30s → 加 30s 失败冷却
（`ovFailAt`），`todayNumbers` 失败也盖时间戳，不再每请求打两条 COUNT。
## 30 天折线补纵轴刻度（`cbb8908`）
- `internal/template/chart.go`：`Polyline`/`AreaPath` 两个函数收敛成 `NewLineChart`
返回 `LineChart{HasData,Max,Points,Area,Ticks}`。**坐标/面积/刻度必须一次算**，
分两次各自归一化会让线和刻度错开半格。
- 纵轴上限 `niceMax(峰值)`（1/2/1.5/3/4/6/8×10^n 向上取整），刻度 上限/一半/0。
1.5 倍只在 mag≥100 时参与（否则算出 7.5 半格）；上限恒为偶数 → 中间刻度必为整数。
- 刻度文字**不能放进 SVG**：viewBox 是 `preserveAspectRatio="none"` 横向拉伸的，
文字会被拉扁。改左边一列 HTML 标签（`.tb-line-y` + 绝对定位 `.tb-line-tick`，
top 用 Go 算好的 `TopPct`），横向虚线仍在 SVG 里（`non-scaling-stroke`）。
- 列宽靠看不见的 `.tb-line-ruler`（最宽那条刻度）在流内占位撑开，不写死 em。
- 面积路径改为沿基线 `h-padBottom` 闭合（原来落到 viewBox 底边，会漏进轴标签留白）。
- 全零/空数据只出轴不出线（`HasData`），否则一条贴基线的直线看着像"数据都是 0"。
- `internal/template/chart_test.go`：锁三条不变式 + 0..2000 穷举。
- 视觉自检：900px 亮/暗 + 390px iframe（Windows headless 最小窗宽 ~485px，不能直接缩窗）。
## 取证：`GetHotQuestions` 的 `ORDER BY updated_at DESC`（未改代码）
- **先纠正前提：这个方法全仓零调用点**，只有接口声明 + 实现（`route/` 里 Questions 的
15 个调用方法不含它；`git log -S` 自 baseline 起也没删过调用）。属死代码，线上零影响。
- 连真库实测（临时测试，跑完已删）：
- 两条公开已答问题：old 9 天前回答 / new 1 小时前回答 → `GetHotQuestions` 得 `new old`；
- `SetRead(old)` 后 → `old new`（名次被翻）；`SetPinned(old)` 同样；
- 换 `ORDER BY COALESCE(answered_at, updated_at) DESC` → 稳定 `new old`；
- old 的 `answered_at` / `updated_at` 相差 216h。
- 机制：`dbutil.Model.UpdatedAt` 是 GORM 约定字段，任何 `Update/Updates/Save` 都会刷新。
所以污染源不止「标记已读」：`SetPinned` / `SetPublic` / `SetPrivate` / `UpdateCensor` 全是。
- **同类残留（仍在线上生效）**：`QuestionStats` 的 `LastAnswerAt = MAX(updated_at)`，
被老的 `/api/v1/site-stats` 用着（首页已不 fetch，但公开接口还在）。实测被推到当下，
比真实最后回答晚 1 小时。新 `/stats` 页已改用 `COALESCE(answered_at, updated_at)`。
- 另：`analytics.go` 的「今日回答数」也用 `updated_at >= since`（注释已承认偏大），未改。
## 已改（`8380fc9`）：删死代码 + 修 LastAnswerAt
- 删 `GetHotQuestions`（接口声明 + 实现）。零调用点、唯一实现者 `*questions`、无 fake/mock。
- `QuestionStats.last_a` 改 `MAX(CASE WHEN answer <> '' THEN COALESCE(answered_at, updated_at))`。
先写测试跑红（偏差 216h）再改绿，回退路径另有一条测试。
- 影响面只有 `/api/v1/site-stats`（`last_answer_at` + `text`），字段名/结构不变，值变准。
- 性能：5 万行实测 7.9ms vs 8.0ms，3 次重复差 −0.5~1.8ms（噪声带内，约 30ns/行）；
执行计划仍 Seq Scan + Aggregate，且该接口有 30 分钟缓存。
- 仍未改：`analytics.go:202` 今日回答数用 `updated_at >= since`（置顶会算进"今日回答"），
改它会直接改变 /stats 首页数字，留待用户决定。
## 已改（`219adef`）：今日回答数也换 answered_at
- `TodayCounts` 今日回答：`answer <> '' AND updated_at >= ?` → `answered_at >= ?`。
实测：三天前回答的旧问题依次 SetPinned/SetPrivate/SetPublic → today answers 1→2（改前）。
- 口径 = 「今天**首次**被回答的提问数」，与文案「今日回答 / Answered today」一致；
改写回答不重置 answered_at，所以改写不算今日回答（有意）。
- 性能：`answered_at` 无索引 → Seq Scan；但 `updated_at` 本来也没索引，同样是 Seq Scan。
20 万行实测 36.7ms vs 38.0ms（3.5%，噪声级）。**没加索引**，注释里留了
「真慢了再加 idx_questions_answered_at」。
- ⚠️ 顺手发现：`analytics.go` 注释原写「只扫当天数据（走 created_at 索引）」，
但「今日回答」那半句一直不是索引扫（updated_at 无索引）。已改正注释。
- 测试：`TestTodayAnswersIgnoreNonAnswerWrites`（改前红 1 vs 2，改后绿）。
## 已改：/stats 脚注去掉「数据基准日」、「计算于」→「快照时间」
- 用户反馈「计算于」表达怪：它其实只是**累计数字与图表**那份快照的生成时间，
而今日两项在缓存命中时会被 `withToday` 换成更新的读数 —— 放在页脚最底部读起来像「整页时间」。
- 「数据基准日」与它 100% 重复：`DataDate` 就是 `UpdatedAt` 的日期部分（同一个 `now`），
删掉 `stats.foot.dataDate` 词条 + `Overview.DataDate` 字段（模板/预览测试同步改）。
- 页脚从 4 行变 3 行：快照时间 / 最后一条提问 / 最后一条回答；「今日两项实时」由下面
的 `stats.foot.cacheNote` 说明，不塞进标签里。
- 词条：快照时间 / 快照時間 / Snapshot: / 集計時刻（`stats.foot.updated` 改名改值）。
- i18n 有词条数量对等测试，删键必须四个语言一起删。
.workbuddy/memory/2026-10-25.md
-126
View File
@@ -1,126 +0,0 @@
# 2026-10-25
## /stats 文案清理：把「写给运营者看」的话删掉
用户指出「数据速览」下面那句「下面几句是从上面的数字直接读出来的，没有推测」怪 ——
那是对他自己说的（作者视角的免责），不是对访客说的。顺着扫了页面全部 40 余条文案。
改动：
- **删 `stats.insight.note`**（四语言 + 模板那行 `<p class="tb-card-note">`）。
卡片留「数据速览」+ 列表即可；`stats.insight.empty` 保留。
删掉说明行后标题与列表之间只剩 4px，给 `.tb-insights` 补 `margin: 8px 0 0`。
- **`stats.foot.cacheNote` 去掉实现细节**：「当天重算一次的快照（当天第一次访问时算，
服务重启也会重算）」→「累计数字与图表每天更新一次」。访客不需要知道缓存是懒重算、
也不需要知道重启会触发重算；准确的新鲜度由「快照时间」那行给出。
- 顺手修了 `templates/stats.html` 里一条过期注释（还写着「四条时间」「基准日」，
上一轮已改成三行「快照时间」）。
保留未动（判断过，不属于这个问题）：
- `stats.foot.privacy` 与顶部 `stats.lead` 的后半句近乎同义（隐私声明重复一次）——
页脚隐私声明是惯例，重复不算噪音，故保留。
- `stats.today.tag` 的「（实时）」在 60s TTL 下仍成立，不改。
## 约定（已写进 topics/stats.md）
页面文案一律以**访客**为第二人称对象：不写实现细节（缓存、重启、索引），
不写作者视角的免责（「没有推测」「这里只有」「本文」这类把读者当审稿人的话）。
数据来源/隐私/新鲜度这些确实要对访客交代的事，放 `stats.lead` 与页脚注。
## 环比句改成「点明月份 + 条数」
用户问「上月提问量环比 -75.0%」是不是「上月同期比本月同期」。**不是**——实际比的是
两个**完整自然月**（9 月 vs 8 月）。但这个问题本身就是证据：句子里「上月」和「环比」
两个相对词叠着，读者得先做两次翻译，很容易读成「同期对比」。
- 新句：`9 月收到 5,620 条提问，比 8 月的 4,890 条多了 14.9%。`
EN：`September had 5,620 questions; August had 4,890, up 14.9%.`
- 口径没变（仍是上月 vs 上上月，本月没过完不参与），只换表达。
- `page.go` 新增 `monthText`：CJK 一律「9 月」，英文用 `time.Month().String()`
（"month 9" 不是英语），不带年份——相比的两个月相邻。
- 三个词条 `momUp/momDown/momFlat` 取代 `mom`：方向词没法塞进同一个模板，
四种语言语序不同。参数顺序统一（本月份名/条数、对比月名/条数、|pct|）。
- `|pct| < 0.05` 走持平，避免「多了 0.0%」。
- 测试：`TestInsightMoMNamesBothMonths`（上升/下降/持平三分支，断言两个月份名 +
两个条数都在句子里）、`TestMonthText`。
- 顺手修预览测试：`GrowthMoM` 原来写死 12.3，与 `monthly` 造的数据对不上，
而新句会同时印出两个月的条数 → 截图会显示「5620 比 4890 多了 12.3%」这种假证据。
改成从 `monthly[10]/monthly[9]` 算。
## 安全评估（AI 挖洞背景下的一次全量自检）
报告：`outputs/security-audit-2026-10-25.md`，脚本在 `outputs/sec-audit-2026-10-25/`。
结论：无 getshell / SQLi / 未授权读数据；但 2 个 P1 直击「匿名」承诺。
### P1-1 匿名提问可植入远程图片（去匿名化）
- `markdown.go` 的 `safeURL` 只校验协议，`<img src=https://任意域>` 能原样输出。
- 唯一挡住它的是审核「广告_引流类」维度，而该维度**只在 strict 档生效**
（`censor/policy.go`：standard 只有 Abuse/Contraband，lax 为空）。
- 实测：账号切 standard → `<img src="https://tb871870.example.org/standard.png">` 直接入库并渲染；
切回 strict 才被拒。→ 修法必须在 `markdown.go` 层限制 img src 为站内/白名单，不能依赖档位。
- 同时确认 8 种混淆（实体编码、`java\tscript:`、协议相对 `//`、反斜杠）都被审核识别。
### P1-2 访问密码可爆破 + 提问密码校验早于验证码
- `UpdatePagePassword`/`UpdateAskPassword` 只有 `maxlen:30`，**无 minlen**，可设 1 位。
- `page.go` 的 `New()` 第一件事就比对 AskPassword，验证码要到后面才校验 →
实测「错误提问密码 + `deadbeef:999999`」返回「提问密码错误」而不是验证码错误 →
**猜密码完全不消耗验证码**。限额 30/min（ask）、10/min（page）。
### 其余P2/P3
- 登录开放重定向：`to=/\evil.example` → `Location: /\evil.example`，浏览器按 WHATWG
把 `\` 当 `/` → `https://evil.example/`。`path.Clean` 不处理反斜杠。
- 注册接口枚举邮箱（返回「已注册」），与 forgot-password 的防枚举口径不一致。
- 无 CSP；`X-XSS-Protection: 1` 过时；`/user` 无 `Cache-Control: no-store`。
- 限流/自动封禁是进程内存态（多副本叠加、重启清零）。
- 匿名投票身份 = `vote_fp` cookie，清 cookie 即换身份，仅 200/min/IP 兜底。
- 登录 `to` 兜底是死代码：`path.Clean("/"+to)` 恒非空 → 登录后永远落 `/` 而非箱主页。
- JSON 响应无 `Content-Type`（实测 text/plain）；429 无 `Retry-After`。
### 无法从外网确认的一项
`trust_proxy` 真实值。三种伪造头（XFF / X-Real-IP / EO-Client-IP）各 22 次都不被采信
（好的方向：无法伪造绕限流），但这既可能是 `trust_proxy=false`（→ 按 CF 边缘 IP 聚合，
限流与封禁会误伤整片区域），也可能是 true 且在 CF 侧删了 EO-Client-IP。需登服务器看 app.ini。
### 已验证没事（别重复怀疑）
CSRF 绑 uid（无 token POST → 400）；18 条 XSS 载荷全灭；跨箱题目/投票越权全 302；
页面密码对主页/整箱分享图/单题分享图/API 四个出口都生效；pixel/service/ShareCard 无 SSRF；
`exec cwebp` 不接用户输入；SMTP 默认校验证书；`RegenerateID` + `pwd_ver`；TLS1.0/1.1 拒绝；
无 CORS 头；测试站蜜罐已开（`/.git/HEAD`、`/.env` 返回假后台）。
### 测试卫生
- 测试站账号 `tbunread1022181904`，脚本已把严格度恢复 strict、清空 page/ask 密码、
删除本轮 15 条测试提问（115–129）。下次复用前先确认这三项是干净的。
- 隔离 venv 里装了 `requests`（`~/.workbuddy/binaries/python/envs/default`），
比 urllib 顺手；`/api/captcha/generate` 限流 20/min，批量提交脚本必须带 429 重试。
## 安全评估（续）：trust_proxy=true 引出的 P1-3
用户确认两套环境 `trust_proxy = true`。据此重做了 IP 采信那一块，发现比原来的推断严重：
### P1-3 双 CDN 下权威头优先次序反了
- `internal/shared/ip.go` 的 `ResolveClientIP` **无条件**先读 `CF-Connecting-IP`，再读 `EO-Client-IP`。
- 前提「权威头只能由 CDN 写入」只对 Cloudflare 成立：
- CF：强制覆盖 `CF-Connecting-IP`，客户端伪造直接 **403**（生产/测试站实测一致）。
- **EdgeOne：不剥离客户端传入的 `CF-Connecting-IP`**，`share.shiroko.one` 实测带该头返回 200
（响应头 `Server: edgeone makers` / `EO-LOG-UUID`）。
- 代码优先读 CF 那个头 → 走 EO 线路时客户端 IP 完全可控。后果：限流/IP 黑名单全失效，
且 `autoban.Record` 可被用来**栽赃任意 IP**（填别人的 IP 连打 10 次敏感路径 → 对方被封）。
- **今天打不通**：`box.shiroko.one` 境内递归（AliDNS DoH）只解析到 `cloudflare.182682.xyz` → 104.18.x/172.64.x，
文档里写的境内 `eo.dnse4.com` 线路已不在；`box.tama.guru` 301 跳新域名也走 CF。差一条 DNS 记录。
- 修法：权威头也套 `isTrustedProxy(remote)`（回环可用 cloudflared 本机场景），fail-closed；
EO 侧删 `CF-Connecting-IP`；日志同时记 `remote_addr` 与解析后 IP。
### 源站定位（外网已尽力，未找到）
- `box.shiroko.one` CNAME `cloudflare.182682.xyz`（第三方 CF SaaS 优选，zone 不在我们手里，
其 Transform/WAF 规则无法自查）。
- certspotter 枚举 `*.shiroko.one` 11 个、`*.337845818.best` 19 个子域，逐个解析全部落
Cloudflare / 腾讯 EdgeOne / Vercel（216.198.79.x、64.29.17.x），**无一条直连记录**。
- `status.shiroko.one`、`share.shiroko.one` → 43.174.246.43/247.43，用 box 的 SNI 访问回 418 Teapot
→ 是 EO 边缘不是源站。
- 结论：源站隐藏目前成功，但「找不到」≠「不可达」，仍需服务器侧 `security-selfcheck.sh local` 确认
`listen = 127.0.0.1:5877`。
### 顺带修正
上一版报告曾把「三种伪造头都不生效」推断为 `trust_proxy` 可能为 false —— 那是错的解读：
无论 true/false，限流键都落在我自己的真实 IP 上，外部不可分辨。已在报告第四节改正。
.workbuddy/memory/2026-10-26.md
-67
View File
@@ -1,67 +0,0 @@
# 2026-10-26
## 修复 P1-3：CDN 权威客户端头未校验来源
用户确认：生产/测试 `trust_proxy = true`，回源是 **cloudflared Tunnel 回本机**（对端 127.0.0.1）；
境内 **EdgeOne 已取消**（实测期国内速度不理想），将来可能重新启用。
### 改动
- `internal/shared/ip.go`
- 新增 `headerSourceTrusted(remote)`：对端是回环 或 命中 `trusted_proxies` 才允许采信权威头。
- `ResolveClientIP` 把 `CF-Connecting-IP` / `EO-Client-IP` 读取整体收进该判断；公网对端忽略。
- 公网对端带权威头 → `sync.Once` 一条 WARN（`remote_addr` + `header_ip`），覆盖「伪造」与
「CDN 直连回源忘登记网段」两种情形。
- XFF / X-Real-IP 信任范围未变（仍只认 `trusted_proxies`，回环不隐含信任）。
- `internal/shared/ip_test.go`：原 4 个用例按新契约调整；新增
`RejectsForgedHeaderFromPublicPeer`（4 种伪造组合）`TrustedProxyHonorsCDNHeader`
`IPv6LoopbackHeader` `LoopbackDoesNotTrustXFF`；加 `setTrustedProxies` 助手（还原包级状态）。
- `conf/app.sample.ini`（CRLF，用脚本按行块改，未破坏行尾）+ `internal/conf/static.go` 注释同步。
### 验证
- 变异验证：把 `headerSourceTrusted(remote)` 临时改成 `true`（旧逻辑）→ 回归用例 3 个子项失败；
还原后全绿。确认测试咬得住。
- `go build -overlay dev/overlay.json ./...` 通过；排除 `internal/storage`（overlay 桩缺
`fitsWithin`/`aspect` 等辅助函数，属既有问题）后全包测试通过。
### 环境坑（值得记）
- 本机 `go` 是 1.25.5，`go.mod` 要 1.27.3；`GOSUMDB=off` 会让工具链校验失败（
"verifying module: checksum database disabled by GOSUMDB=off"），`GOTOOLCHAIN=local` 又降级到 1.25.5。
解法：直接调缓存里的工具链
`~/go/pkg/mod/golang.org/[email protected]/bin/go.exe`，配 `GOTOOLCHAIN=local`。
- Python 读 CRLF 文件要显式 `newline=''`，否则 universal newline 把 `\r\n` 归一成 `\n`，
`split('\r\n')` 只会得到 1 行（踩过一次，误判文件被写坏）。
### 待办
P1-1（img src 白名单）、P1-2（密码 minlen + 验证码顺序）、P2-3（`to` 开放重定向）均未动。
## 修复 P1-1 / P1-2
### P1-1 外链图片（`internal/template/markdown.go`）
- 新增 `safeImageSrc()`：`<img src>` 只允许站内相对路径（无协议部分）或主机命中自有图片出口
（`image_bucket_cdn_host` / `aliyun_bucket_cdn_host` / `<bucket>.<endpoint>` / `external_url` 主机）。
- 含反斜杠一律拒（`\` 在浏览器等价 `/`）；`//` 先于「以 / 开头=站内」判断；
`url.Parse` + `Hostname()` 比对 → 后缀 / userinfo 把戏失效。
- `img` 无合法 src 时**整段丢弃**（只删 src 会留 `<img alt>` 变成破图）。
- `a[href]` 仍走 `safeURL`（外链需点击，产品上要允许）。
- 测试：`TestSafeImageSrc`（12 条拒绝）+ `TestMarkdownToHTML_ImageSource`（端到端）；
变异验证：`safeImageSrc` 直接 return true → 7 条拒绝用例失败。
### P1-2 密码（5 个文件）
- `minlen:6` + `form.PasswordMinLen`；handler 里 `rejectTooShortPassword()` 二次校验（rune 计数）；
前端 `minlength=6 maxlength=30` + 提示文案「6–30 位，留空则关闭」；i18n 新增
`form.profile.passwordLen` / `question.errPasswordLocked`（4 语言）。
- 校验顺序：抽 `askPasswordDenied()`，从 `New()` 首行挪到**两个分支验证码之后**（私聊 + 普通提问各一次）。
没把验证码提到最前——会让「箱已关闭」「需登录」变成验证码错误。
- 失败锁定：新增 `shared.AttemptLimiter`（无后台 goroutine，惰性清理 + 键数上限）；
`pagePasswordGuard(5, 10min, 10min)`，键 = 箱主ID + LimitKey(IP)。锁定期内不比对密码。
### 端到端验收脚本
`outputs/sec-audit-2026-10-25/verify_p1_fixes.py`（`--only p1-1,p1-2a,p1-2b,p1-2c`）。
**在未部署的旧版本上四项全 FAIL，已实测** → 证明检测有效；部署后应全 PASS。
踩到的两个判定坑（写脚本时记下来）：
- 提问成功页是 **200**（不是 302），不能用状态码判断提交成功。
- 受保护的箱是**在 `/_/<domain>` 内联渲染密码表单（200）**，不是跳转 `/password`；
判断「有没有密码闸门」只能看页面里有没有 `action="/_/<domain>/password"`。
- 箱主页与 `/api/v1/user/<domain>/questions` 都**不暴露题目 id**（无后台），
要定位刚建的提问只能扫 `/_/<domain>/<id>`（脚本里 `question_ids_with_marker`）。
.workbuddy/memory/2026-10-27.md
-92
View File
@@ -1,92 +0,0 @@
# 2026-10-27
## 在 WSL Debian 上把 TamaBox 跑起来，做 P1 修复的端到端复验
用户新搭了 WSL2 Debian，给了 `data/data.txt`（测试环境的 PG / Redis / OSS 凭据），要求「用它部署测试一下」。
**环境**（详细踩坑见 `topics/build.md` 的「本地部署」小节）：
- `wsl.exe -d Debian -u root` 可免密进 root；apt 装了 `redis-server / python3 / python3-requests /
gcc / libwebp-dev`（有 libwebp 后 `s3.go` 正常编译，不用 s3stub overlay）。
- Go：`/opt/go` 装 1.27.3，但 `~/.bashrc` 里 `GOROOT=/usr/local/go`（1.26.3）→ 必须 `env -u GOROOT`。
- PG：新建 role `tamabox`（CREATEDB）+ 库 `tamabox`、`nekobox`（schema `nekobox`）。
- 服务：`/etc/systemd/system/tamabox-test.service`，源码在 `~/tb/src`，二进制 `~/tb/tamabox`，
日志 `~/tb/server.log`，端口 5877。配置 `~/tb/src/conf/app.ini`（`production=true`、
`external_url=http://127.0.0.1:5877`、`captcha_type=math`、`enable_text_censor=false`、`trust_proxy=true`）。
**验收结果（全 PASS）**：
- P1-1 外链图片剥离 / 白名单图片保留 / 实体与反斜杠变体；
- P1-2a 4 位密码被拒、6 位生效；P1-2b 验证码先于密码；P1-2c 6 次失败后正确密码仍被锁；
- P1-3 A/B：回环对端 + `CF-Connecting-IP: 1.2.3.4` → 命中黑名单 302；Windows 侧（非回环）同样头 → 忽略并 WARN；
- 回归：18 条 XSS 载荷无可执行/无外联、CSRF 无 token 400、越权全 302；
- 单测：`internal/{template,shared,form,conf,db,route}` + `route/{question,vote}` 全绿。
**这次揪出的新问题（已修）**：P1-1 的白名单把配置串整串当主机名，而真实配置是
`image_bucket_cdn_host = "r2.337845818.best/tamabox"`（host/path）→ 自家 R2 图片被一起剥掉。
修法：`normalizeHostLike()` 归一化（补协议 → url.Parse → Hostname），endpoint 主机自身也入白名单
（R2 path-style 链接是 `<endpoint>/<bucket>/…`）；新增 `TestSafeImageSrc_RealConfiguredHosts`，
变异验证（退回旧逻辑 → 4 条放行用例变红）。**教训：白名单类单测必须照抄生产配置的写法，不能自己编一个好写的形态。**
**P2-3 从推断升级为实测**：`/login?to=/\evil.example` 登录后 `Location: /\evil.example`，
按 WHATWG 解析 = `http://evil.example/`；`\\evil.example` 同样外跳（`//`、`///` 已被规整）。
同一载荷在正文渲染里是安全的（`<a href="/\example.org">` 被剥成 `<a>`）。修复未做，等用户指示。
**产物**：
- 报告新增「六、本地部署实测」章节（`outputs/security-audit-2026-10-25.md`）；
- 脚本新增 `verify_p1_allow.py`（正向放行）、`local_seed.py`（本地注册审计账号），
`audit.py` 改为 `TB_BASE/TB_EMAIL/TB_PWD/TB_DOMAIN` 可覆盖 + 验证码 429 退避。
**待办**：改动仍未 commit / push；P2-3、P2-4、P2-5、P2-6、P2-7 未动。
---
## 第二轮：修完 P2/P3 + 全局复查
用户：「把你发现的问题修了，然后全局检查一遍有无其他问题」。
**已修（P2-3～P2-8、P3-9～P3-15）**：都写进 `topics/sec.md` 的「第二轮修复」。要点：
跳转白名单收敛到 `shared.SafeRedirectTarget`（`url.Parse` 会解 `%0d%0a`，必须逐 rune 查 `u.Path`）；
注册三条失败分支共用 `registerSucceeded`；CSP 三档 + umami 的 `mami.shiroko.one` 必须入 `script-src`；
`no-store`；`securityHeaders` 前移；封禁落库 `ban_records`；常量时间比较；页码上限；429 统一出口。
**全局复查新发现 3 个**（详见 `topics/sec.md`）：
1. 🔴 `chat_handler.SendMessage` 的 POST 缺 `conv.OwnerID != pageUser.ID` —— 被拉黑者换 domain 即可继续骚扰
+ 触发邮件 + 绕过屏蔽词/日限额。已修，3/3 PASS，并做变异验证（去掉校验后对应用例变红）。
2. 🟡 页面密码 `next` 的反斜杠外跳（与 P2-3 同源）。
3. 🟡 分享卡无字体时每请求烧数秒 CPU（公开端点）→ 失败结果缓存 1 分钟，实测 3.44s → 0.53s。
**验收**：`verify_p1_fixes.py` 4/4、`verify_round2.py` 19/19、`verify_page_next.py` 6/6、
`verify_chat_owner.py` 3/3；单测全绿；全项目编译通过。测试数据已清（库里只剩 `tb-local@example.com`）。
**报告**：`outputs/security-audit-2026-10-25.md` 新增「七、第二轮修复与全局复查」。
**再待办**：仍未 commit / push（26 改 + 9 新）；CSP 是否切 `enforce`；生产机补 glyf 轮廓字体。
**收尾复跑发现两个「假红」**（已写进 `topics/sec.md`）：① 不给 `TB_BASE` 时脚本打的是远端
box-dev-api，没部署修复所以 4/4 FAIL；② 页面密码入口限流 10 次/分钟 + p1-2c 的 10 分钟锁定
会让 `verify_page_next.py` 后两项 429。顺手把该脚本判据从「Location 不含 evil」改成精确比对
`/_/<domain>`、每条载荷开新会话、429 单独报错。四套最终：4/4、19/19、6/6、3/3。库已清回只剩 `tb-local`。
---
## 第三轮：用户「按最优解决定」→ CSP 切 enforce + 字体落地 + 提交
**CSP 默认改 enforce**（`cspMode()` 空值 = enforce；写错值仍退 report）。依据不是猜：
写了 `outputs/sec-audit-2026-10-25/csp_sweep.py` + `csp_sweep.cjs`（Playwright + 本机 Chrome，
监听 `securitypolicyviolation`），report 模式先测一遍、enforce 再测一遍，**18 页面 + 2 图片端点零违规**。
巡检器自己做了变异自检（页面里主动 `fetch("http://csp-selftest.example/x")` → 确实报 connect-src），
否则「0 违规」可能只是监听器没挂上。
**补的漏项**：`browser.sentry-cdn.com` —— header.html 里 Sentry 在 `{{ if ne SentryDSN "" }}` 里，
本地没配 DSN 所以巡检碰不到，线上一开就会静默失效；现在按 `conf.App.SentryDSN` 条件放行 + 单测双向断言。
**分享卡字体**：补 glyf 系统候选（wqy-zenhei / wqy-microhei / DroidSansFallback / uming）并压到
Noto(CFF) 之前；`static/fonts` 同时按 CWD 和可执行文件目录找；`CheckShareCardFont()` 在 runWeb 里
启动即探（命中 Info 带路径，缺失 WARN 给 apt 命令）。实测 `apt install fonts-wqy-zenhei` 后
零配置即 `font=…wqy-zenhei.ttc`，`/share-card` 与单题分享卡从 500 → `200 image/jpeg`，
中文/二维码正常（图存 `outputs/sec-audit-2026-10-25/sharecard-*.jpg`）。
**提交**：三个 commit（7802bb2 安全修复 / e807dea 字体 / 430c6ef 记忆）。**push 失败**：
`git.shiroko.one` 的 https 存取凭据被拒（`Failed to authenticate user`），SSH 路（`id_ed25519_wsl`）
也未被该仓库授权 —— 需要用户更新 token 后自己 push。
**全量单测**：带 `DB_TYPE=postgres DB_USER=tamabox DB_PASSWORD=… DB_HOST=127.0.0.1` 全绿；
不带 DB 变量时一批 DB 门控用例会报 `Unknown database type: ""`（不是回归）。
.workbuddy/memory/2026-10-29.md
-381
View File
@@ -1,381 +0,0 @@
# 2026-10-29
## 第二轮综合复查（非安全向）
用户要求「再确认还存在什么问题与风险点」+「从用户角度有什么值得改进和增加的功能」。
前一轮是安全专项（P1/P2/P3 全修完），这轮换到**业务正确性 / 运维 / 前端体验 / 产品能力**四个面。
产出：`outputs/review-2026-10-29.md`（分级清单 + 复现方式 + 产品建议）。
### 实测复现的两条 P0
1. **私聊 50 条截断**：`GetByConversationID` 是 `Order("created_at ASC") + Limit(50)`，
唯一调用方永远传 nil cursor；会话上限 200 → 第 51 条起**写库成功但永久不可见**。
本地造 55 条实测：页面只渲染 #1–#50。这不是性能问题，是「数据在库里但用户看不到」。
2. **访问日志泄露 token**：`flamego.Classic()` = `Use(Logger(), Recovery(), Static())`，
Logger 记 `RequestURI`（含 query）。实测日志出现 `path=/_/tblocal/4?t=SECRETTOKEN123`。
`?t=` 是私密题钥匙、`?code=` 是改密凭证。**tracing 中间件早就为同一风险避开了 RequestURI
并写了注释，框架默认 Logger 漏了。**
### 代码确认的 P1
- **无优雅关闭**：全仓 `signal.Notify`/`Shutdown` 零命中，SIGTERM 直接杀进程 → 每次重启掐断在途 POST。
- **提问入库后图片失败不回滚**（`page.go:660` → `:680`），叠加 DuplicateGuard 5 分钟 → 用户以为没发出、5 分钟内不能重提。
- **Redis 两种故障**：session 在 Redis 上宕机即全站 500（flamego session load 直接 panic）；
`cache.Cacher` **没有** `if conf.Redis.Addr != ""`，空 Addr 被 go-redis 回退到 localhost:6379 → 没配 Redis 时找回密码静默坏掉。
- **处置不覆盖投票**：提问链路 7 处 `ActiveLevel`，投票链路 0 处。L4 处置后 `/_/domain` 已 302 到 /restricted，
但 `/vote/{token}` 照常可投、可发新投票、探索页照常曝光。
### 产品缺口（重要，别忘）
- **完全没有访问量数据**：`SiteAnalytics` 是全站聚合，无 per-user 维度，也没有 page view 表。
箱主无法知道自己被看了多少次。
- **提问者找不回自己的提问**：不填邮箱时唯一手段是成功页那条链接，关页即失联；全仓 `localStorage` 零命中。
→ 建议前端用 localStorage 记 `{domain, id, token}`，箱主页显示「你有 N 条提问已被回答」。
- `NotifyType` 只有 `email` / `none`，无 Telegram / Webhook。
- 模板零 `application/ld+json`（SEO 富摘要缺失），无 RSS。
- 图片原图直传（无前端压缩），配合 ReadTimeout 30s → 手机端 8MB 图必超时。
### 顺带确认的「不用动」
四语言字典 917 条完全对齐（`TestDictionaryComplete` PASS）、深色模式正文对比度 4.8–6.8:1 达标、
gzip 实现质量高、后台移动端短标签方案做得细。
### 已修（同日，六项全部端到端验证）
| # | 改动 | 验证 |
|---|---|---|
| 1 | `GetByConversationID` 改 `id DESC` 取最新 + 内存反转，limit 取 `conf.Limits.ChatMaxMessages`；游标配 DESC | 55 条会话实测渲染 55 条（改前 50）；单测 3 项 + 变异（改回 ASC 变红） |
| 2 | 弃 `flamego.Classic()`，`flamego.New()` + 自写 `accessLogMiddleware`（只记 `URL.Path`；静态成功不记、4xx/5xx 记） | 日志 `msg=access path=/_/tblocal/4`，token 计数 0 |
| 3 | `signal.NotifyContext` + `srv.Shutdown(15s)` + 关连接池 | 8 个并发分享图请求中 SIGTERM → 8/8 成功 |
| 4 | 图片失败分支 `Questions.DeleteByID` 回滚 | 6MB 图 → 提问增量 0 且 `deleted_at` 非空；无图对照增量 1 |
| 5 | `cache.Cacher` 加 `if conf.Redis.Addr != ""`（否则 MemoryIniter）；启动 `PingRedis` fail-fast | 停 Redis 后启动立即失败并指向 Redis |
| 6 | 投票 Page/Submit 加 L4、VotePublish 加 L2、探索页用 `ActiveLevels` 批量过滤 | L4 → `/vote` 302 到 /restricted；探索页该投票 0→2（撤销后）；L2 下发布停 draft，撤销后 published |
新增 `vote.err.restrictedPublish` 四语言 key。回归：4/4、19/19、6/6、3/3，全量单测 + `go build ./...` 通过。
**踩到的两个坑**（值得记）：
- 消息加载的兜底写成 `limit < 50 → 50`，会把箱主显式配置的小上限抬大，测试直接测出这个语义错误。
兜底只该处理**零值**（未初始化），不该替用户改配置。
- Python 的 **bytes 字面量不支持 `\uXXXX`**（只有 str 支持），写字面量 `b'...\uff08'` 会原样写入
`\uff08` 六个字符。CRLF 文件的字节级替换要用 `\xef\xbc\x88` 或 `.encode()`。
### 第二批（P2 + 高价值 P3，Docker 按用户要求跳过）
| # | 改动 | 验证 |
|---|---|---|
| 7 | ReadTimeout 30s→120s（8MB 图需 ≥68KB/s；ReadHeaderTimeout 仍 10s 防 slowloris） | 参数修正 |
| 8 | 投票结果改 stale-while-revalidate：过期先返旧值 + 后台按投票去重重算；Submit 从「删缓存」改「标记过期」（新增 `cache.Expire` / `GetWithExpiry`） | 2 万条：冷启 0.211s → 过期首读 0.023s（9.2x） |
| 9 | 三处幂等：`MarkDeletedByOwner` 条件更新+RowsAffected、`SetPinnedIfCurrent`、追问「上一条已回复」移进事务 | DB 测试 3 项全过 |
| 10 | 私聊首条三写入合并为一个事务（`CreateWithFirstMessage`） | message_count 与实际消息数一致 |
| 11 | `/healthz` + `/readyz`（DB ping 失败 503） | 停 PG 后 healthz 200 / readyz 503 |
| 12 | 验证码失败改同请求渲染，不再丢正文 | 200 + 正文回填 + 不建提问 |
| 13 | `tbBeginSubmit()` 抽出，reCAPTCHA 回调补防重复 | 静态验证（7 个模板受益） |
| 14 | waline 按页加载、`loading="lazy"`、safe-area、三处硬编码接字典（+4 key×4 语言） | /login 无 waline；en 页面零中文残留 |
| 15 | 5 处裸类型断言改带 ok | 编译 + 单测 |
新增 `verify_round3.py`（6 项）。第二批回归：6/6、4/4、19/19、6/6、3/3，全量单测 + build 通过。
**判据随实现更新**：`verify_p1_fixes.py` 的 p1-2b 原来用「是否 302」判断验证码先于密码，
第 12 项改成 200 后判据失效 → 改为「200 且页面报『验证码错误』」。语义不变，判据跟着渲染方式走。
### 这次踩的第三个坑（重要，我自己造成的）
**Windows 上 `Path.write_text()` 默认把 `\n` 转成 `\r\n`**，用它改 LF 文件会让整个文件行尾翻车。
- 症状：`gofmt -l` 突然把整文件标为未格式化。
- 后果：`git diff --stat` 会显示整文件重写。
- 正确写法：`path.write_text(s, encoding="utf-8", newline="\n")`，或用 bytes。
- **排查手段**：`git diff --stat` 是判断行尾污染最快的信号 —— 真实改动应该只有几十行，
整文件重写一定是行尾变了。恢复方式：`git show HEAD:<file>` 取其行尾，再统一替换回来。
另：本项目 `core.autocrlf=true`，仓库里存 LF、工作区 checkout 成 CRLF，
所以「工作区看到 CRLF」不等于「仓库里是 CRLF」，判断基准要看 `git show`。
---
## 第三批（数据安全 + 产品缺口）
1. **删除投票 / 删除提问改成一个事务 + 真删（`Unscoped`）**。
原来四步独立写入、前几步失败只 Warn → 中途失败留下「选项没了票还在」这类
界面修不好的状态，重试时投票已不存在、只能报 not exist。
更关键的是：所有模型都带 `dbutil.Model` 的软删除，原来全是软删 ——
提交记录里的参与者文本、`voter_ip`、`voter_token`、提问里的 `FromIP`
只是「界面上看不见」，库里永久留着。用户点删除的预期是删掉。
2. **配额与内容同事务**：抽出 `incrementQuotaTx(tx, userID, feature, delta)`，
提问 `Questions.Create`、私聊 `CreateWithFirstMessage`、投票提交
`VoteSubmissions.Create`（新增 `QuotaUserID` 字段）都在自己的事务里 +1。
原来 handler 里独立写入且失败只 Warn，`quota_count` 会永久偏低。
3. **追问改回答不再重复发邮件**：`UpdateAnswerByID` 返回 `wasFirst`（事务内读旧值判定），
handler 只在首次回答时发。原来改三遍措辞就发三封。
4. `isQuestioner` 的 token 比较改 `subtle.ConstantTimeCompare`（与 Pager 中间件同口径）；
CSV 导出的**表头与选项列**补 `sanitizeCSVCell`（原来只有数据列走它）。
5. 写路径功能开关改 **fail-closed**：新增 `db.FeatureStateOfStrict`，
读配置失败时拒绝而不是回退默认「开启」。
6. **真 404 + HTML 500**：新增 `internal/route/errorpage.go`，`f.NotFound` 不再 302 到首页，
改 `writeErrorPage(ctx, 404, ...)`；`flamego.Recovery()` 换成 `recoveryMiddleware()`。
7. **提问者找回自己的提问**：成功页写 localStorage，箱主页显示提示条，
新增 `POST /api/v1/ask-status`（批量问「哪些已被回答」）。
### 这批踩到 / 学到的
- **flamego 的 `f.NotFound` 拿不到组级中间件**：`template.Templater` 与 `Contexter`
（含 session、CSRF）都挂在 `f.Group("", ...)` 上，NotFound 不经过它们。
所以在 NotFound 里注入 `template.Data` 会直接 panic：
`unable to invoke the 8th handler: value not found for type template.Data`。
错误页最终用**内联 HTML + i18n.T**（`pickErrorPageLang` 从 Accept-Language 猜语言），
不依赖模板系统 —— 错误页本来是最后一道防线，不该依赖可能出错的链路。
- **`gofmt` 会把注释里的列表规范化**：`// 1) ...` 会被改写成 `// 1. ...`。
自己写的中文注释列表如果用了 `1) 2) 3)`，`gofmt -l` 会标为未格式化 —— 不是行尾问题。
- **`Select(...)` 漏列 = 字段静默为空**：`ListByIDsAndUser` 一开始只选了
id/token/answer/created_at，摘要永远是空串，接口 12 项里就这一项红。
- **配额口径要按功能分别确认**：投票的定量收集是「累计收到的票数」（在提交成功时 +1），
不是「创建了几个投票」。所以我一度在删除投票里加了 -1，那是错的 —— 删投票不代表票没发生过。
- **CDP 验证纯前端功能的套路**（`verify_ask_history_ui.mjs`）：
`chrome --headless=new --remote-debugging-port=9222`（必须作为独立后台进程跑，
跟在别的命令后面 `&` 会随 shell 退出被回收）→ node 用内置 `WebSocket` 连
`/json/list` 里任一 target → `Runtime.evaluate` 注入 localStorage → 重新 navigate →
断言 DOM → `Page.captureScreenshot`。注意 headless=new 的空标签页 `type` 常是 `other`，
不能只找 `type === "page"`。
- **控制台错误要区分来源**：页面里 R2 图片的 CORS 报错是既有问题，
把它算进「本次改动失败」只会得到假阳性。判据要按 URL/关键字过滤。
### 待办（仍未做）
- AutoMigrate 无版本化（改列名会静默丢数据）
- 无备份脚本（图片全在对象存储，只备份 DB 恢复后全是裂图）
- 32 个 `<label>` 无 `for=`、语义标签对比度 1.9:1
- 箱主数据面板（全站无 page view 数据）、Telegram/Webhook 通知、JSON-LD + RSS、图片前端压缩
## 箱主数据面板 + 图片前端压缩（本轮完成）
把「待办」里的两项落地，其余（AutoMigrate 版本化、备份脚本、label/对比度、Telegram/Webhook、JSON-LD）仍未做。
### 箱主数据面板（/user/insights）
- 新表 `box_views`（`internal/db/box_views.go`）：一行 = 一访客×一天×一箱，唯一索引
`(user_id, viewed_on, visitor)`，`views` 累加。**刻意不内嵌 `dbutil.Model`**——
软删除 + 唯一索引会让被删行永久占槽（老坑）。
- 访客标识 = `HMAC(日盐, IP)` 前 32 hex（`internal/insights/recorder.go`）：同日可去重（UV 准）、
跨日不可关联（隐私）。代价：近 7/30 天 UV = 各日 UV 之和，文案里已写明。
- 异步记录器：buffered channel 512 + 2s flush，构造即启动 goroutine（避免 Close/Run 竞态），
队列满即丢（统计尽力而为）。过滤：箱主本人、空 UA、爬虫 UA 子串、预取头（Sec-Purpose 等）。
- 聚合层 `internal/db/box_analytics.go`：BoxTrend（提问/回答按日）、BoxHours（24h 分布）、
BoxFunnel（已回答/已读未答/未读 + 回答率 + 24h 回复占比）。复用 analyticsDialectFor 的时区处理。
- 展示层 `internal/insights/page.go`：30 天 PV/UV 双柱趋势（CSS 高度百分比）、时段分布、
漏斗 + 回答率进度条、自动结论（`FormatInsights`）。**百分比整数值不带 .0**（formatPct）。
- 打点：`route/question/page.go` 的 Pager 末尾（所有错误分支/密码页已 return 之后），
`!ctx.IsLogged || ctx.User.ID != pageUser.ID` 才记。
- 挂载：`/user/insights` 在 reqUserSignIn 组内；`pageScope` 加 `/user/insights → admin`。
- 密钥复用 `server.xsrf_key`；`StartMaintenance` 每日清 400 天前的明细。
- 测试：`internal/db/box_views_test.go`（4 项，含「同批同键先内存合并」——PG 的 ON CONFLICT
不允许同条 INSERT 二次命中同一行）、`internal/insights/page_test.go`（pct/窗口切分/visitorID/爬虫过滤）。
### 图片前端压缩（templates/base/footer.html）
- 选图即压：canvas → WebP（长边 1600、质量 0.8，与服务端 GeneralEncodeSpec 对齐）。
- 三条边界：GIF/SVG 跳过（canvas 会把 GIF 变静止首帧）、压完不更小退回原图（<85% 才采用）、
透明 PNG 走 WebP（不支持 WebP 编码时退回 PNG 而非 JPEG，否则透明变黑）。
- `createImageBitmap(..., {imageOrientation:'from-image'})` 摆正 EXIF，老浏览器回退不带选项。
- submit capture 兜底：选图立刻提交时 `preventDefault` + `Promise.all(压缩)` + `form.submit()`，
避免二次触发防重复。
- 实测（CDP + 自写 WebSocket 客户端 `dev/_cdp.py`）：4.6MB PNG → 11.7KB WebP（0.3%），
小图原样保留、GIF 跳过，三断言全过。
### 踩坑（本轮新）
- **同步脚本把 WSL 的 `conf/app.ini` 删了**：Windows 侧用 `tar | wsl rsync --delete` 同步源码，
目标机那份含 DB 密码/对象存储密钥的 app.ini 不在源目录里，被当多余文件删掉 → 服务重启起不来。
修：`dev/sync-wsl.sh` 里 `rsync --exclude "conf/app.ini"`，模板放 `dev/wsl-app.ini`（已 gitignore）。
- **配置丢了怎么找回**：进程内存 dump（`/proc/PID/mem` 扫描 `key = "value"` 模式）能捞出启动时
加载的全部 ini 键值（salt/xsrf_key/上传密钥/DB DSN 都在），配回 `conf/app.ini` 即可。
- **headless 里 canvas 编码大图超时是假象**：Windows Chrome 的 `--dump-dom` + `--virtual-time-budget`
会把 3000×2000 噪声图压得解码超时，`#out` 永远停在 running。换 WSL 内 `apt install chromium`
走 CDP 轮询（`Runtime.evaluate` 非 await 反复读结果）才拿到真值。
- **自写 CDP 的 WebSocket 客户端必须处理 continuation 分片**：CDP 大事件（console/DOM 属性）会
把一帧拆成多段，按「一帧=一消息」解析会让缓冲区永久错位，evaluate 永远等不到响应。修了 `_cdp.py`。
- **awaitPromise 长轮询会挂死自写 WS 客户端**：验证异步结果改用「navigate + 非 await 轮询读 DOM」。
## 全盘复查（数据面板/图片压缩之后的第二轮）
用户要求「再做一次全盘复查」。两个并行子代理扫了本轮新增代码（数据面板、图片压缩、
删除事务化、错误页、找回提问），交叉核对后确认的问题与处置：
### 已修（本轮）
1. **P1 提问真删不彻底**（`questions.go` DeleteByID 对主表 Unscoped，但追问/图片仍软删）：
- `follow_ups.go DeleteByQuestionID`、`upload_images.go DeleteByQuestionID` 改 Unscoped 真删。
- 关联表 UploadImageQuestion 无 DeletedAt，无需 Unscoped（已注释）。
- 新增 `internal/db/question_delete_hard_test.go`：用 Unscoped 计数断言删除后追问/图片/关联行
物理上=0。**变异验证**：把追问改回软删，测试失败（expected 0 actual 1）。
2. **P1 BoxTrend 每日回答数按 created_at 分组**（应为 answered_at）：`box_analytics.go` 加 answerDay
表达式（PG 用 `to_char(COALESCE(answered_at,updated_at) AT TIME ZONE ...)`，MySQL 用 CONVERT_TZ），
WHERE/GROUP/SELECT 三者口径一致。新增 `internal/db/box_analytics_test.go`：构造「40 天前创建、
昨天回答」的提问，断言计入昨天。**变异验证**：改回 d.day 后测试失败。
3. **P2 ask-status domain 存在性可枚举**：`ErrUserNotExists` 分支原返回空数组、正常分支返回带元素数组，
凭空/非空可枚举 domain。改为箱主不存在时也回显 `ok:false`（与「存在但 token 错」完全同形）。
4. **P2 私聊 SendMessage 写路径用 FeatureStateOf**（fail-open 变体）：改 FeatureStateOfStrict，读配置失败即拒。
（此前靠「chat 默认关闭」巧合侥幸安全，现在按写路径约定统一。）
5. **P2 图片压缩 submit 兜底可重复提交**：capture 监听器里 tbBeginSubmit 从 Promise 回调提前到
preventDefault 的同步栈，物理阻止压缩窗口内双击重复提交。
### 判定不修（子代理误报，或有意设计）
- **投票删除不回退配额**：子代理当 bug，但这是**有意为之**——投票配额口径是「累计收到的票数」，
删投票不代表票没发生过（记忆里早记过：一度加 -1 是错的）。注释已写清。
- **recomputeHeights 里 `d.UV > maxPV` 死代码**：UV≤PV 恒成立，该行永不触发，但当前「PV/UV 同刻度」
恰好是设计意图，不算错。
- **TopDays 死代码**：`BoxViewsStore.TopDays` 无调用方，best-day 只回看 30 天。属口径/注释自相矛盾，
但不改数据安全，留待后续。
### 踩坑（本轮新）
- **gofmt -l 把「缺末尾换行」也标为未格式化**：Edit 工具写文件时可能丢末尾换行符，`gofmt -l`
会报 `\ No newline at end of file`。与行尾问题不同，补一个 `\n` 即可。
- **struct 字段对齐**：手写 struct 时字段没对齐（`Questions int64` 少一个空格），gofmt 会标。
用 `dev/gofmt_keep_crlf.py` 统一修。
- **CSRF token 登录后会轮换**：flamego/csrf 在登录成功后轮换 token（防固定），所以登录前 GET /login
拿到的 token 在登录后失效，POST 接口测试要登录后再从带表单的页面重新取。这导致 ask-status 的
真实 HTTP 验证没跑通（靠代码 diff 确认修复正确）。
- **`git show HEAD:file` 输出写到 /tmp 后 Windows Python 读不到**：/tmp 是 Git Bash 的虚拟路径，
Windows Python 看不到。要落盘验证行尾，写到仓库内（如 outputs/）再读。
## 三项待办落地：AutoMigrate 版本化 + 备份脚本 + Telegram/Webhook 通知
用户「先按1-2-3的顺序做」，期间两次纠正 R2 存储结构认知。
### 1. AutoMigrate 版本化迁移（internal/db/migrations.go）
- 新增 `schema_migrations` 表（version 主键 + name + applied_at），`runMigrations(db)` 按版本升序
执行未应用的迁移，每个迁移在事务里「跑 up + 记版本」。
- 把 db.Init 里散落的 5 个幂等补丁收编为版本迁移 v1~v5：
backfillAnsweredAt / backfillFeatureControls / reconcileLegacyChatEnabled /
normalizeChatQuota / normalizeHarassmentSetting。收编后**只跑一次**（原来每次启动都跑）。
- AutoMigrate 仍负责「加表/加列/加索引」（声明式、幂等、无数据丢失），版本迁移负责
AutoMigrate 做不了的破坏性变更（改列名/删列）与一次性回填。两者分工，互不替代。
- 迁移失败阻断启动（半途而废比静默跳过更危险）。
- 测试：migrations_test.go（幂等跑两遍不重复 / 失败阻断后续 / 清单严格升序）。
- 实测：真实库首次启动建表 + v1~v5 落账本，二次重启账本仍 5 行（幂等）。
### 2. 备份脚本（internal/cmd/backup.go，TamaBox backup）
- `--output <dir>` 输出；`--db-only` / `--images-only` 分开关。
- DB：调 pg_dump（PGPASSWORD 环境变量传密码避免 ps 泄漏），输出 db-<ts>.sql（标准恢复格式）。
- 图片：从 R2 下载 tamabox 站全部图片 + 写 images-manifest.json（key→size→md5）。
- 两个 CLI 入口（根 tamabox.go + cmd/tamabox.go）都注册了 Backup。
- 实测：db-only 导出 46KB（21 表全含 schema_migrations）；images-only 30 秒下 15 个文件、
路径保持 tamabox/ 结构、大小与 List 一致。
### 3. Telegram/Webhook 通知（internal/notify/notify.go）
- 站级 Webhook（[notify] webhook_url）：新提问/新回答/新追问/新私聊/新投票回复统一 POST JSON。
- 用户级 Telegram（[notify] telegram_bot_token + users.telegram_chat_id 字段）：新提问/新投票点对点推送。
- 通知是「尽力而为」旁路：任一通道失败只记日志不抛错，不影响业务主流程；未配置则静默跳过。
- 6 处业务触发点接入 notify：page.go（新提问+新私聊）、question.go（新回答）、
follow_up.go（新追问+追问回答）、vote.go（新投票）。私聊消息保留仅邮件（已有节流，避免刷屏）。
- UI：profile 加 telegram_chat_id 输入框 + 四语言字典（admin.notifyTelegram* 3 条）。
- 测试：notify_test.go（webhook JSON 结构 / 未配置跳过）。
### 踩坑（本轮新）
- **R2 存储结构（用户两次纠正，重要！）**：图片实际存在 Cloudflare R2，CDN URL 形如
`https://r2.337845818.best/tamabox/2025/12/1767082504316655685.jpg`（bucket=tamabox，
key=年月/时间戳.扩展名，**无 picture/ 前缀**）。但 R2 API 侧（ListObjectsV2）返回的 key
**带 bucket 名作前缀**（`tamabox/2025/12/...jpg`）——这是 path-style bucket 的 R2 行为。
- 关键：`storage.GetS3Client` 的 endpoint 配置（image_endpoint 带 `/tamabox` 后缀 +
Bucket 参数 tamabox）对 GetObject/PutObject 恰好可用（aws-sdk 拼出 /tamabox/tamabox/<key>，
R2 容错），但 **ListObjectsV2 会拼成 /tamabox/tamabox?list-type=2 → 404 NoSuchKey**。
- 备份脚本的正确姿势：剥离 endpoint 的 `/tamabox` 后缀 + UsePathStyle=true + Bucket=tamabox，
List prefix="tamabox/"，GetObject 直接用 List 返回的完整 key（含 tamabox/ 前缀）。
- 同一 R2 account（0c99...）下还有 blog/ 前缀的另一个站点内容（共享 account）。
- **代码的 PictureKeyPrefix="picture/" 与线上不一致**：mainline 代码上传 key 用 `picture/` 前缀，
但线上历史图片 key 是 `tamabox/` 前缀（即实际 key 无前缀、靠 bucket 隔离）。这是待澄清的
「代码 vs 线上」不一致，本轮未动，需用户确认是否要统一。
- **Windows Edit 又把 3 个 LF 文件转成 CRLF**（conf.go / users.go / form/user.go）：
老坑复发，用 Python `b.replace(b'\r\n', b'\n')` 统一转回 LF 解决。
## R2 存储结构最终定论（用户贴出生产 app.ini [upload] 段后）
生产 app.ini 关键段：
```
[upload]
default_avatar = "https://r2.337845818.best/tamabox/tamabox_low.png"
default_qrbackgroundimage = "https://r2.337845818.best/tamabox/picture/2024/01/01.jpg"
image_endpoint = "https://<acct>.r2.cloudflarestorage.com/tamabox" # 注意带 /tamabox 后缀
image_bucket = "tamabox"
image_bucket_cdn_host = "r2.337845818.best/tamabox"
```
实测铁证（GetObject 精确验证）：
- 生产配置（endpoint 带 /tamabox + Bucket=tamabox + Key）下，`key=2025/12/1767082504316655685.jpg`
返回 OK(187274)，而 `key=picture/2024/01/01.jpg` 返回 404。
- **结论：R2 bucket tamabox 的真实 key = `YYYY/MM/<17位雪花ID>.<原扩展名>`，无 picture/ 前缀、
无 tamabox/ 前缀。**
- 代码 `PictureKeyPrefix="picture/"` + `randstr.Hex(15)` 生成的 key 在 R2 里**根本不存在**。
- `default_qrbackgroundimage` 里的 `picture/2024/01/01.jpg` 是**手动上传的站级静态资源**（孤立的），
不是代码生成的，且该 key 实测 404（可能已失效）。
**重大结论：生产部署的存储层代码 ≠ mainline 仓库的存储层。**
mainline 的 `picture/YYYY/MM/DD/<15hex>`（无扩展名）是一套**从未上线、与生产脱节**的实现；
生产真实用的是 `YYYY/MM/<雪花ID>.<原扩展名>`（无前缀）。差异太大不可能是小改动，
是存储层被整体替换过但改动没合回 mainline。
对备份脚本的影响：
- 备份脚本用「无后缀 endpoint + pathStyle + Bucket=tamabox + prefix=tamabox/」List，
返回的 key 带 tamabox/ 前缀（pathStyle 的 R2 行为），用同一 key GetObject 下载是自洽的、
能下全所有图片（含 picture/ 之外的真实 key）。
- 但落盘路径带 tamabox/ 前缀，与「真实 key 无前缀」在语义上不一致——恢复回传时需注意。
- 待用户决策：是否把 mainline 的 PictureKeyPrefix 和 key 生成逻辑改回生产真实格式
（`YYYY/MM/<雪花ID>.<ext>`），还是维持现状。这是存储层正确性问题，未动。
## 存储层 key 口径对齐生产（已落地）
用户确认「生产就是按 mainline 在 10-25 前最后一次修改部署的，有调整 git 查得到」，并拍板
「先备份当前源码，再按生产口径统一代码」。
### 根因最终定论（纠正之前「雪花ID」的说法）
- 生产 URL 里 `1767082504316655685` 不是雪花 ID，而是 **UnixNano 纳秒时间戳**（19 位）：
`datetime.fromtimestamp(n/1e9)` = 2025-12-30 16:15:04，与路径 `2025/12` 完全吻合。
- **生产口径 key = `YYYY/MM/<UnixNano>.<原扩展名>`**（无前缀、无 day 层）。
- 铁证：`route/question/page.go:uploadImage`（提问配图入口）**早就是这个格式**：
`uploadKey = fmt.Sprintf("%d/%d/%d%s", now.Year(), now.Month(), now.UnixNano(), fileExt)`。
脱节的只有 `internal/storage` 包里三个函数（UploadAvatarToS3 / UploadBackgroundToS3 /
UploadPictureToS3 及 UploadPictureToOSS），它们还在用老的 `picture/ 前缀 + YYYY/MM/DD + 15hex + 无扩展名`。
- git 历史是**浅快照**：`PictureKeyPrefix` 只在 `e3e59e7 "chore: baseline snapshot"`（2026-09-10，
却是「最早提交」）出现一次，之前之后都没改过 —— 完整历史在快照之外，10-25 前的改动追溯不到。
### 改动（internal/storage/）
1. `picture.go`：`PictureKeyPrefix` 改 `""`；新增三个辅助函数：
- `uploadKey(ext)` → `YYYY/MM/<UnixNano><ext>`（唯一 key 生成点）
- `extFromContentType(contentType)` → MIME→扩展名映射（保证 key 扩展名与 ContentType 严格一致，
避免「.jpg 实为 webp」错配）
- `originalExt(filename)` → 取原扩展名并小写（OSS 原图直传通道用）
2. `s3.go`：key 生成改 `uploadKey(extFromContentType(contentType))`；删除 day 变量与 randstr 依赖。
注意转换成功用 `.webp`（contentType=image/webp），回退原图用原格式扩展名（contentType=image/jpeg→.jpg）。
3. `oss.go`：`UploadPictureToOSS` 的 `_ *multipart.FileHeader` 改 `fileHeader`（取原扩展名），
原样上传不转 webp，key 用 `uploadKey(originalExt(...))`。
4. 新增 `picture_test.go`：锁定 key 格式正则 `^\d{4}/\d{2}/\d{16,19}\.jpg$` + ext 映射 + originalExt。
### 验证
- gofmt 通过；`go build ./...` 通过；storage 全量测试 + 新增测试 PASS。
- 行尾：三个文件都是 LF（工作区 LF），Edit 未破坏（HEAD 对比行数变化正常，非整文件重写）。
### 踩坑（本轮新）
- **go 版本假象**：`go version` 报 1.27.3（GOROOT 指向 toolchain 目录），但 `GOTOOLCHAIN=local`
时暴露真实工具链是 **1.25.5**；go.mod 要求 1.27.3。正确编译姿势：直接调已下载的 toolchain 二进制
`$HOME/go/pkg/mod/golang.org/[email protected]/bin/go.exe`，
或去掉 GOSUMDB=off 让 toolchain 校验通过。用 `GOTOOLCHAIN=local` + 系统 go 会报
`go.mod requires go >= 1.27.3 (running go 1.25.5)`。
- **备份目录别放 .go 文件**：把 storage 源码备份到 `outputs/backup-*/` 后 `go build ./...`
会把备份当 Go 包编译（undefined: announcementConfig 等）。备份的 .go 文件要改 `.go.bak` 后缀，
或放到仓库外。
- **fmt 的 `%s` 对 int64**：`fmt.Sprintf` 用 `%s` 拼 int64 能编译但 `go vet`（测试时自动跑）报
`%s has arg of wrong type int64`，且语义模糊。纳秒时间戳必须用 `%d`。
.workbuddy/memory/2026-10-30.md
-106
View File
@@ -1,106 +0,0 @@
# 2026-10-30
## 蜜罐周期安全汇总（周报/月报 + 地图 + 邮件）
用户需求：以周/月为单位汇总安全状况，把嗅探 IP 通过**公共服务**查地理位置，汇总到**地图**，
发到邮箱。起因是他发现线上有人隔一段时间换不同 IP 探测蜜罐。
### 关键认知：ipinfo 与 geoip 是两个维度（用户亲自纠正）
用户反馈「ipinfo 只能查机房，肉鸡全显示『未识别（普通网络）』」。原因是
`internal/security/ipinfo` 走 `projectdiscovery/cdncheck` 的离线 ASN 指纹，只认云厂商/CDN/WAF。
它答的是「**是不是代理**」，不是「**在哪儿**」。肉鸡（家宽、企业宽带、移动网络）必然是后者，
所以安全汇总必须另建一套真正的 IP 地理库 → 新包 `internal/security/geoip`。
### 新增文件
- `internal/security/geoip/geoip.go` — ip-api 批量打底（100/批、1.4s 节流）+ 腾讯精修国内
（只精修前 200 个，一 IP 一请求）。`Result{Geo, Unresolved, Requests, Failures}` 三态。
- `internal/security/report/{period,aggregate,mapdraw,html,geo,countryname}.go`
- `internal/db/{ipgeo,security_report}.go` — `ip_geo_cache`（主键 = `LimitKey`）、
`security_report_logs`（`period_key` 唯一索引保证幂等）
- `internal/cmd/report.go` — `honeypot report --period week|month` + 30 分钟一轮的调度器
- `templates/mail/security-report.html`
### 踩过的坑（都要记住）
1. **ip-api 免费版很慢**：22 个 IP 实测 4–10 秒，且同一批重复请求更慢。最初设 15s 超时 →
第一次真实数据就整批超时、定位率 0%。现在 `defaultTimeout = 45s` + 重试一次。
2. **缓存毒化**：早先把所有 miss 都写缓存并 `Failed=true`（TTL 3 天）→ 一次网络抖动
等于把整批 IP 钉成「查不到」三天，报告定位率莫名变 0 且无任何线索。
现在只有服务**明确回答**没数据才允许写失败缓存；请求失败绝不写。
3. **`addrs` 不能从 map 取顺序**：腾讯精修只取前 N 个，若按 map 迭代（随机）取，
每次运行精修到的 IP 都不同，配额花在长尾上。必须按 `keys` 原始顺序（= 命中数降序）建。
4. **地图标签会叠出假数字**：同一都市圈两个城市坐标只差 0.01°，标签精确重叠，
「AU 55」+「AU 30」叠成了看起来像 **AU 305** 的字符串 —— 读图的人会当结论。
已加 `labelPacker`（不重叠才画，右侧放不下换左侧）。
5. **不能无脑把腾讯结果的国家码写成 CN**：`provider=tencent` 时海外 IP 也走这条路。
现在从 `ad_info.nation` 精确判「中国」才给 CN。
### 合规（地图）
自绘底图**零国界**，只画经纬网 + 气泡 + 度数刻度；真实底图交给腾讯地图（配 key 才有，
未配给申请指引）。代码里不预置任何 key，测试里有禁词断言（googleapis/mapbox/osm/bing）。
报告里 HK/MO/TW 统一显示为「中国香港 / 中国澳门 / 中国台湾」（`countryname.go`），
且常见国家改用中文名（报告是给中文读者看的）。
### 端到端验证（WSL Debian + PG 17.11）
854 条仿真数据 / 22 个来源：首跑 36s（真实 ip-api）、次跑 1.3s（缓存命中），
定位覆盖 22/22、14 个国家/地区、未能定位 0 次。
### 顺手修的（别人改动留下的）
- `internal/route/honeypot_test.go` 的 `captureStore` 缺 3 个新方法 → 整个 route 包编译不过
- `templates/render_test.go` 的 `mockLoggedUser` 缺 `TelegramChatID` → 3 个渲染测试失败
## 蜜罐邮件提醒功能审阅（用户要求，重点找 bug 与改进点）
审阅报告：`outputs/review-honeypot-mail-2026-10-30.md`。基线测试全绿（mail + route 蜜罐相关）。
### 结论分级
- **P1（应修）`autoban.alerted` 去重口径不一致**：`map[string]bool` 永不过期，且 `cleanup()`
从不清理它 → 同一 IP 的告警**一生只发一次**；而蜜罐侧 `dedup` 用 24h TTL。两条链路口径不同，
长期盯防同一来源会漏掉后续攻击活动。建议改成带时间戳的 map + cleanup 按窗口清理。
- **P2（建议修）蜜罐告警空收件人不短路**：`route/honeypot.go:alert()` 没有
`SecurityAlertEmail == ""` 前置判断（autoban 侧有 `alertEmail != ""`）。蜜罐开着但没配收件人时，
每次凭据提交都走一遍无效 SMTP 拨号 + 留 Warn 日志，与「未配置静默跳过」预期不符。
- **P2（边界）邮件明文密码**：`SendHoneypotAlertMail` 把明文 password 渲染进 HTML。代码已意识到
是敏感物。建议维持明文（功能价值=运维立刻拿到字典）+ 强化「收件人必须是个人邮箱、禁群组」的
配置警示，而非一刀切掩码。
### 审阅中确认「已做对、无需改」的点（值得记住的设计）
- 凭据**类型层面**不入库：`db.HoneypotHit` 结构体没有 Username/Password 字段，编译期保证；
明文只落 0600 按天 JSONL。
- 蜜罐独立于 `enable_auto_ban`（`RecordHoneypot` 只看 `HoneypotEnabled`）。
- 纯 GET 探测不立即封（留「GET 表单→POST 提交」的咬钩机会）。
- 精确 IP 与 /64 封禁键分离；body 只读一次先提取凭据再判封禁；`clipRunes` 按 rune 截断防非法 UTF-8。
### 三项已修（commit 036156b）
1. **P1 `autoban.alerted` 去重口径**：`map[string]bool` → `map[string]time.Time`，新增
`alertCooldown = 24h` 常量 + `alertedRecently()` 辅助 + `cleanup()` 清理过期项。
与蜜罐侧 `alertDedupTTL=24h` 对齐。新增 `TestAlertCooldownExpires`（回拨 alerted 时间戳
模拟冷却期已过，断言能再次告警）。
2. **P2 空收件人短路**：`route.go` 注入 `sendAlert` 前判 `SecurityAlertEmail` 空值，空则置 nil，
`alert()` 的 `h.sendAlert == nil` 自然短路。（autoban 侧本就有 `alertEmail != ""` 判断，无需改。）
3. **P2 明文密码警示**：`conf/static.go` 注释 + `app.sample.ini` 注释强化「蜜罐邮件含明文密码，
收件人必须个人邮箱、禁群组/分发列表」。维持明文不改掩码（功能价值=运维立刻拿到字典）。
验证：autoban/route/mail/conf 测试全绿，`go build ./...` 通过，gofmt 干净，行尾未破坏（LF）。
## 更新日志文档 + 首页间距修复
1. **更新日志**：`outputs/changelog-2026-10-30.md`，站长口吻、口语化，只写用户可感知的功能
（数据面板/Telegram 通知/找回提问/图片压缩/404 页/验证码不丢正文/私聊完整记录）。
蜜罐、备份、迁移等纯后台内容刻意不写。注意：Telegram 条目依赖生产配好 [notify] 的 bot token。
2. **生产配置答疑**：蜜罐子项全有 sanitizeHoneypot 兜底，无需补；真正要显式加的是
honeypot_cred_dir、报告配置段（report_email 留空回退 security_alert_email）、[notify] 可选段。
生产 ban_window_seconds=10 比默认 60 短，已提示用户确认是否有意。
3. **首页间距修复（ea9ba3e）**：`templates/home.html` 里 tb-grid 之后的三张独立卡片
（域名迁移/一点提醒/近期更新）彼此零间距挤成一团。修法：`.tb-grid ~ .uk-card { margin-top: 16px }`
（模板内联 <style>，不碰 base.css，无需 bump StaticVersion）。
截图验证：headless=old + file:// 预览页，亮暗两主题间距均正常。
**坑：headless Chrome 的 --screenshot 相对路径写不进**（Failed to write file），必须用绝对路径。
.workbuddy/memory/topics/builder.md
-74
View File
@@ -1,74 +0,0 @@
# 主题生成器 `dev/theme-builder/`（长版明细）
## 主题生成器 `dev/theme-builder/`
- `serve.py` 起静态服务（8777），iframe 加载 `outputs/preview-*.html`。**file:// 下父页读不到 iframe DOM**，必须走 HTTP。
8777 常由用户自己起着，改完直接刷新。
- 单文件 `index.html`（约 2900 行）。图片处理**非破坏**：`orig` 存原始字节 + `fx` 存参数，每次从 orig 重算；
参数没变则跳过重编码。画质（`S.export.quality/maxSide`）同理 —— 改完 `rebakeAll()` 从 orig 重来，不叠加压缩。
- **尺寸单位** 4 档：`fit`（按视口高，人物）/ `fitw`（按视口宽，横幅）/ `px` / `vh`。
`layerSize()` 出 CSS、`unitGeom()` 出预览框，**两处必须共用同一函数**，否则「框没超、图已裁」。
⚠️ 下拉的 value 用 `l.unit`，不能用 `unitOf(l)`（后者把 fit 归一成 vh → 选了 fit 却显示 vh）。
- 溢出检测 `layerMetrics(l, a, VW, VH)`：算 left/top/overL/R/T/B，编辑器里显示「显示 131×420，完整可见」或
「⚠ 左右各 88px 越界」，并给「按当前视口修好」按钮（切 px + 算刚好放下的尺寸）。导出前 `overflowReport()` 再扫一遍。
- 视口预设**带高度**（1512×900 / 1280×800 / 1024×768 / 820×1180 / 390×844）：裁切几乎全由高度决定，
只改宽度模拟不出来。`fitStage()` 按预设高渲染 iframe。
- 窄屏：全局 `hideDeco`（急停）> 每层 `mob`（inherit/scale/hide）> 尺寸单位（fit/fitw 自己就缩）。
⚠️ **`hideDeco` 会把 @media 里 10 槽全写 none** —— 桌面完全正常、手机上素材全没了，
这是「素材在窄屏消失」的头号来源（test01 就是这么中招的）。UI 已在勾选时给橙色警告、
图层行标「窄屏隐藏」、加层/导出再提醒；`?narrow=hide` 可一键复现。
⚠️ `@media` 里**每个独立配置的 scope 都要写一条** `[data-page-scope="x"]`：页面覆盖块特异性 (0,2,1)，
只写 `html[data-theme-style]`(0,1,1) 的话独立配置页在手机上完全不生效。
⚠️ 竖版图只替换**本来有背景图**的页面（`cfg.bg` 非空），否则等于给纯色页塞了张图。
- ⚠️ **派生文字色必须走对比度下限，不能按固定比例混**：`paletteVars` 里
`text-secondary = mixToContrast(text, backdrops, 5.5)`、`text-muted = 4.5`（WCAG AA）。
旧的 `mix(text,bg,0.55)` 在浅底只有 2.9:1 —— 每导一次主题就把 base.css 的 AA 修复覆盖回去。
- 半透明卡片（`--tb-surface: rgba(255,255,255,0.86)`）必须 `flatten()` 压到底色再算，否则按纯白算偏低；
- 参考背景取「页面底色 + 压平后的卡片」两者更不利的那个；
- 手填正文本身不达标时**原样返回**（宁可不够淡，不能产出看不见的字）。
- 配色面板有读数（正文/次要/淡文字/主色），<4.5 变橙；默认 primary 已压到 `#3d6fac`(4.63)。
- 还要导出 **`--tb-on-primary`**（白字 `#ffffff` / 深字 `#0b1016` 里挑对比度更高的）：
深色模式主色偏亮，白字只有 2.2~3.1:1。主色卡中间调时两种字都不够 → 面板橙色提示 +
`?dump=palette` 的 `warnings`，**不判失败**（是主色要调，不是工具挑错）。
- 自检钩子：`?dump=css|zip|validate|install|fx|fxpipe|fxkey|layers|fit|quality|palette`，`?demo=1&fresh=1&rows=N&scope=&loadurl=`
（`?demo=1` 已含 fit 层 + 竖版背景，`@media` 才会生成）。用法：
`chrome --headless=old --virtual-time-budget=12000 --dump-dom "http://127.0.0.1:8777/dev/theme-builder/index.html?demo=1&fresh=1&dump=fit"`
抓 `<pre id="dump">`（正则要带属性：`<pre id="dump"[^>]*>`）。
- ⚠️ **canvas `toDataURL('image/webp', 1)` 不能用**：Skia 在 q=1 切无损，输出反常（噪声图 q=1 只 52KB，
q=0.95 是 440KB）。`canvasAsset` 夹到 0.95，滑块上限也是 0.95。
- ⚠️ 平涂/线稿降 q 可能**变大**（有损引入噪点）。压体积先砍长边，再降 q。缩小走 `imageSmoothingQuality='high'`。
- ⚠️ 面板只有 ~240px：`input[type=range]` 有固有宽度，必须 `flex:1 1 0;width:0;min-width:0`，
且数值放进 label 里（第三个小 flex 项会被顶出可视区）。
- `?dump=css` 的产物要过 Go 侧校验：临时存成 `static/css/themes/<非下划线名>.css` 再 `go test ./internal/theme`，
跑完删掉。
- 导出面板「素材前缀」`S.assetBase`：空 = `/static/images/themes/<slug>/`；填了 = CSS 写绝对 URL
（R2/OSS）。**图片地址只能由 `urlOf()` 决定** —— `layerCSS` 曾复制过一份拼接，改一处会出现
「背景走 CDN、装饰还指本地」。文档见 `docs/theme-assets-cdn.md`。
- **素材托管（2026-10-21）**：面板两选一 `S.host.mode = local|s3`，字段
endpoint/region/bucket/prefix/pathStyle/publicBase 进工程，**accessKey/secretKey 只进
sessionStorage**（`SEC_SESSION_KEY`），绝不进草稿/工程 json/导出 zip（有断言）。
`publicBaseOf()` 手填优先，空则按 endpoint 推导（path 风格 `<ep>/<桶>/<前缀>`）——
对 R2 这个地址不可匿名读，测试的「匿名可读」只给 warn 不拦。
- **上传走 `serve.py` 代理**，浏览器不直连对象存储：不用配 CORS，密钥不发给第三方。
端点 `/api/s3/ping`（探测能力，`python -m http.server` 没有 → 按钮禁用）、
`/api/s3/test`、`/api/s3/upload`。上传集合与导出共用 `usedAssetIds()`。
- ⚠️ **`usedAssetIds()` 返回 Set**：`!ids.length` 恒真、`ids.map` 不存在 → 上传永远报
「还没有素材」。用 `[...usedAssetIds()]` 展开。
- ⚠️ **SigV4 手写，必须对拍**：`dev/theme-builder/check_sigv4.py` 调
`dev/sigv4ref`（aws-sdk-go-v2 的 `signer.SignHTTP`）逐字节比。6/6 一致才可信。
- 只用 ASCII 用例：裸 `SignHTTP` 默认**二次转义** URI，而 S3 client 内部把
`DisableURIPathEscaping` 设成 true（单次编码）。我们跟随 S3 client / AWS 文档 RFC3986。
- canonical headers 三件套 `host;x-amz-content-sha256;x-amz-date`，与 SDK 相同；
CanonicalHeaders 自身以 `\n` 结尾，故其后与 SignedHeaders 之间有一个空行（规范如此）。
- ⚠️ **HEAD 桶失败拿不到 `<Code>`**（HEAD 响应无 body）→ 只能按状态码归因
（403→AccessDenied / 404→NoSuchBucket / 301|307→PermanentRedirect）。想拿真错误码要靠 PUT。
- ⚠️ **Windows 上 8777 可能被上一个进程继续占着**（SO_REUSEADDR 让新进程 bind 成功但抢不到
accept）。症状：`/api/s3/ping` 返回旧版 404，而代码明明改了。用
`Get-NetTCPConnection -LocalPort 8777` 查 PID，或换端口验证。
- 自测：`python dev/theme-builder/check_sigv4.py`（签名对拍）、
`python dev/theme-builder/selftest_upload.py`（假 S3，16 项）、
`python dev/theme-builder/mock_s3.py --port 9900`（手动点面板）。
- 顶栏面板 `S.navbar={mode,alpha,blur}`：solid/glass/clear 三档，基色仍取「配色 → 顶栏」，
`navbarValue()` 统一算；glass 额外写 `.uk-navbar-container:not(.uk-navbar-transparent){backdrop-filter}`。
**clear 只给预览**，`validate()` 与 `TestNavbarNotFullyTransparent` 都拦。
自检 `?dump=navbar`。
.workbuddy/memory/topics/coop.md
-7
View File
@@ -1,7 +0,0 @@
# 协作（长版明细）
## 协作
- 结论分级 P0/P1/P2；给建议前先根因取证 + 实测复现，别只静态推断。
- 改代码前先出变更清单；重大问题显式指出。用户常授权自主推进。
- 用户是运营者也是圈内人：处置必须可解释、可留痕、可申诉，不做自动级联封号。
.workbuddy/memory/topics/embed.md
-15
View File
@@ -1,15 +0,0 @@
# 行尾 / 模板 / embed（长版明细）
## 行尾 / 模板 / embed
- 行尾混合不可推断（`internal/db/*`、`mail.go`、`route/user/profile.go` 是 LF；`internal/route/route.go`、
`users.go`、`i18n/dict_*.go`、`route/question/*.go`、`base.css`、`dev/theme-builder/*` 是 CRLF）。
改前用 Python 数 `b'\r\n'`；`gofmt -l` 会把 CRLF 误报为未格式化 → 走 `dev/gofmt_keep_crlf.py`。
Edit 工具会保留原文件行尾，可放心用；新增整份文件用 Write 时要自己补 CRLF。
- 往 gofmt 对齐组中间插键会污染 diff，新键插组末；注释别用 `''`（gofmt 改成 `”`）。
- ⚠️ **`templates/embed.go` 是显式清单**：新增**顶层**模板必须加进 `//go:embed`，否则运行时
`html/template: "xxx" is undefined` → 500，编译期无提示。`static/fs.go` 同理。
- ⚠️ **`//go:embed` 的 `*` 不匹配 `_` / `.` 开头的文件**：`static/css/themes/_scaffold.css` 与
临时建的 `_gentest.css` **都不进 embed**，`TestDecoSlotCount` 扫不到它们（表现是"校验了但数字没变"）。
验证生成的主题 CSS 要临时改成非下划线文件名。
- `templates/user/moderation-strictness.html` 只用 shell/python 改（Edit/Write 会注入 `data-page-node-id`）。
.workbuddy/memory/topics/gorm.md
-9
View File
@@ -1,9 +0,0 @@
# GORM（长版明细）
## GORM
- 默认值必须带引号；`default:` 会把零值替换，空串有语义的字段别加。
- ⚠️ 事务里复用同一 `tx` 会串条件，每句 `tx.WithContext(ctx).<链式>`。
- ⚠️ 软删除 + 唯一索引 = 槽位永久占用：停用（可恢复）= 物理删内容 + 软删用户行，注册侧 `Unscoped` 给
`ErrDeactivatedEmail/Domain`；封禁 = 物理删用户行，邮箱释放。级联删除一律 `Unscoped()`。
- ⚠️ GORM 链式对象 Count/Find 后带状态，统计/预览/更新必须各自重建 query。
.workbuddy/memory/topics/honeypot.md
-34
View File
@@ -1,34 +0,0 @@
# 蜜罐（多家族伪装 / 取证 / 封禁）
## 结构
- `internal/security/honeypot/family.go` 是**唯一皮肤表**：9 个 Family
（wordpress / phpmyadmin / tomcat / jenkins / grafana / gitlab / luci / joomla / generic）。
每个 skin 自带 routes、title、brand、tagline、css、fields、hidden、failure、headers、cookies。
- `FamilyOf(path)` 按 segments 前缀判定（`.` 也算边界，兼容 `/adminer.php`）。
新增路径必须**同时**进 `honeypotPrefixes`，否则 `Match` 根本不接管。
- `asset.go`：`/wp-admin/css/…`、`/wp-includes/js/…` 这类资源回占位内容，
**不落库、不计数** —— 一次页面加载会打 5–10 个资源请求。
- `page.go`：一次 `strings.Builder` 拼接，禁用 `"a" + b + "c"`（每个 + 一次分配）；
`fieldIDReplacer` 必须包级，别在循环里 `NewReplacer`。
- `route/honeypot.go` 的 Serve 顺序：cleanPath → **资源短路** → 家族 → 诊断日志 → 回环告警 → 提凭据 → 封禁 → 响应 → 落库。
## 性能基线（谁改慢了谁负责）
- `RenderFamily` ≈ 3.7 µs / 2 allocs / 5.2 KB；`AssetFor` ≈ 55 ns / 0 alloc。
- 单页体积上限 4 KB，由 `TestRenderIsCheap` 守。
- 预览：`go run ./dev/preview-honeypot` → `outputs/honeypot-preview/index.html`（9 个 iframe）。
改皮肤后务必跑一次并截图，上一版就是靠它发现 Tomcat 按钮没背景色。
## 坑
- **hidden CSRF token 不能算密码键**：PMA / GitLab 的表单带 `token`，而 map 遍历无序，
一旦 token 进 `isPasswordKey`，真密码会被随机覆盖成 token 值。
所以 `credentialKeys` 收 token（只用于判 `HadFields`），`isPasswordKey` 不收。
- **Tomcat 家族 = 401 + `WWW-Authenticate`**，凭据从 `Authorization` 头取；
给它一个 HTML 表单反而不像。
- 页面里不能出现 `TamaBox` / `honeypot` 字样；canary 只放 HTML 注释，
`<meta name="generator">` 必须伪装成真实产品（扫描器必查）。
- WP 登录页底部不能挂 404 文案（真实页没有，挂上一眼就假）。
- 新增诱饵前缀前先核对业务路由（`/user`、`/login`、`/api`、`/_/`…）；
`forbiddenPrefixes` 按 `/xxx` 段边界判断，所以 `/users/sign_in` 不会被 `/user` 连坐。
.workbuddy/memory/topics/quality.md
-72
View File
@@ -1,72 +0,0 @@
# 业务正确性 / 运维 / 前端体验（2026-10-29 第二轮复查）
安全向的结论在 `sec.md`。这里是非安全向的四类，完整清单见 `outputs/review-2026-10-29.md`。
> **状态**：下列「已实测确认的缺陷」「处置覆盖面」「Redis」三块已于同日修复并端到端验证。
> 紧接着做了第二批（P2 + 高价值 P3，共 9 项）：投票结果 stale-while-revalidate、
> 三处幂等、私聊首条事务、`/healthz` `/readyz`、验证码失败保正文、`tbBeginSubmit`、
> waline 按页加载 / lazy / safe-area / i18n、5 处裸断言。
> 第三批（同日）：删除投票/提问改事务 + 真删、配额与内容同事务、追问改回答不重复发信、
> token 常数时间比较 + CSV 注入补齐、写路径 fail-closed、真 404/HTML 500、
> 提问者找回自己的提问（localStorage + `/api/v1/ask-status`）。
> 条目保留是为了记住**为什么**会踩、以及验证该怎么做。
## 已修：两个 P0（都是实测出来的）
- **私聊 50 条截断（P0，已修）**：`internal/db/message.go` 的 `GetByConversationID` 是
`Order("created_at ASC") + Limit(50)`，而唯一调用方 `chat_handler.go:97` 永远传 `nil` cursor。
会话上限是 200 → 第 51 条起写库成功、`message_count` 在涨、页面显示 51/200，但列表永远只有最早 50 条。
实测造 55 条，页面只渲染 #1–#50。**取最新 N 条要 `Order("id DESC")` 再内存反转**；
游标 `id <` 也必须配 DESC（配升序会反复返回同一页）。
- **访问日志泄露 token（P0，已修）**：`flamego.Classic()` = `Use(Logger(), Recovery(), Static())`，
`Logger()` 记的是 `ctx.Request().RequestURI`（含 query）。实测出现
`path=/_/tblocal/4?t=SECRETTOKEN123`。`?t=` 是私密题钥匙，`?code=` 是改密凭证。
**tracing 中间件早就为同一风险避开 RequestURI 并写了注释，框架默认 Logger 漏了。**
改用 `flamego.New()` + 自写访问日志，只记 `URL.Path` 与白名单 query key。
## 处置（restrict）的覆盖面（投票已补齐）
- 提问链路 7 处 `ActiveLevel`（page L4 / question L3 / setPublic L2 / followUpAnswer L2 / shareCard 全级 / ListAPI L4 / moderation 锁定）。
- **投票链路 0 处**：`vote.Page`、`vote.Submit`、`VotePublish` 都不查。L4 处置后 `/_/domain` 已 302 到
`/restricted`，但 `/vote/{token}` 照常可投、可发新投票、探索页照常曝光。
- **教训：新增任何「用户发起」的写入口，都要问一句「这里要不要查 ActiveLevel」。**
## 运维面
- **无优雅关闭**（已修）：全仓 `signal.Notify` / `server.Shutdown` 零命中，SIGTERM 直接杀进程。
`web.go` 里 `ListenAndServe` 一把梭。每次部署都掐断在途 POST。
- **Redis 两种故障**（已修）：session 走 Redis 时 load 失败会 `panic`（flamego/session），被 Recovery 兜成 **全站 500**；
`cache.Cacher` 没写 `if conf.Redis.Addr != ""`，空 Addr 被 go-redis 回退 `localhost:6379` →
「不配 Redis」的部署里找回密码静默坏掉、私信邮件节流失效。启动时该 `PING` 一次并 fail fast。
- `ReadTimeout: 30s` 与 8MB 单图上限冲突（手机 4G 上行 1–2 Mbps → 8MB 必超时），正文也一起丢。
- 无 `/healthz`：`route.Home` 不碰 DB，DB 挂了 `/` 仍 200。
- `Dockerfile` 用 `golang:1.20` 而 `go.mod` 是 1.27.3 → **构建必失败**；`-X` 路径还是旧仓库名
`github.com/NekoWheel/NekoBox`，`BuildCommit` 永远是 `dev`。
- AutoMigrate 无版本化：GORM 只加列不删列，**改列名会静默留下旧列 + 新列全 NULL**，比迁移失败更难发现。
- 备份只有 `docs/cli.md` 一句 `pg_dump`；用户图片全在对象存储，**只恢复 DB = 全站裂图**。
## 前端
- `templates/question/history-template.html` 有硬编码中文（查看回答 / 加载更多 / 无更多留言），en/ja 用户直接看到。
`vote/page.html:140` 中英混排。**字典本身 917 条 × 4 语言完全对齐（有测试守着），问题只在模板层。**
- 提问页验证码失败走 `SetErrorFlash + Redirect` → **整段提问内容丢弃**；其他分支都是
`SetError + Success` 保留内容。最常见的失败反而最不该丢内容。
- `form.submit()` 不触发 submit 事件 → 验证码流（默认 captcha_type）完全没有防重复点击。
- `waline.js` 全站加载但只有 `home.html` / `item.html` 用；UIkit CSS 走第三方 CDN 且阻塞首屏。
- 32 个 `<label>` 无 `for=`；语义标签白字对比度约 1.9:1；全仓零 `loading="lazy"`。
- 移动端 `body{padding-bottom:56px}` 与 `env(safe-area-inset-bottom)` 冲突，iPhone 上遮住约 32px。
## 产品缺口（按 ROI）
1. **提问者找不回自己的提问**：不填邮箱时唯一手段是成功页那条链接，关页即失联。
全仓 `localStorage` 零命中。最小解：前端记 `{domain, id, token}`，箱主页显示「你有 N 条提问已被回答」。
2. **箱主没有自己的数据**：`SiteAnalytics` 是全站聚合（只有 `COUNT(DISTINCT user_id)`），
**全站没有 page view 表**。箱主不知道自己被看了多少次、回答率多少。
3. `NotifyType` 只有 `email` / `none`，无 Telegram / Webhook。
4. 模板零 `application/ld+json`（SEO 富摘要），无 RSS。
5. 图片原图直传，无前端压缩。
## 这一轮确认「不用动」的
四语言字典对齐、深色模式正文对比度 4.8–6.8:1、gzip 实现（204/304/Content-Length/Vary/Flusher 都处理对了）、
后台移动端短标签方案。这几块质量高于平均，别为了统一风格去改。
.workbuddy/memory/topics/review.md
-61
View File
@@ -1,61 +0,0 @@
# 审核 / 处置 / 举报（长版明细）
## 审核 / 处置 / 举报
- 线上通道 = 七牛（`ai.qiniuapi.com/v3/text/censor`，antispam）；`[security] text_censor_source = qiniu|aliyun|auto`。
七牛只硬拦涉政/暴恐/色情，`review` 放行 → 裁决在 `censor/policy.go` + `moderation.Check`。
- **新增审核调用点必须走 `moderation.Check`**（直调 `censor.Text` 绕过档位）。不可用时 **fail-closed**。
- ⚠️ 圈内黑话（代称+群体标签+避雷叙述）通用审核拦不住，别指望词库；靠处置 + 举报 + 人工判断。
- 严格度 lax/standard/strict 存 `users.moderation_strictness`；**受处置用户强制 strict**：
`moderation.EffectiveStrictness(ctx, userID, raw)`（7 个入口已改）。**查询失败回退用户设置**
（否则 DB 抖动会让全站突然加严）。处置期内拒绝保存 + 设置页 disabled。
- ⚠️ **同请求渲染只能用 `ctx.SetError` / `SetInternalError`，不能用 `*Flash`**：flash 写 session，下次请求才读 →
提示静默丢失。`Set*Flash + Redirect` 才是正常模式。扫描法：找 flash 调用 → 向下第一个 `Success(`/`Redirect(`。
- 处置四级：L1 停止分发／L2 收窄公开（新回答强制私密、禁 set-public）／L3 冻结发布（仍可收信）／
L4 整页停用（`/restricted`）。到期靠 `expires_at`，**无 cron**；`restrict` 是**替换语义**；比较用 `RestrictionAtLeast`。
- ⚠️ L2 强制私密必须在**审核通过之后**，且与写回答**同一条 UPDATE**（`AnswerByIDPrivate`）：
拆开会留下「公开+已作答」窗口，第二条失败还会变成「私密+无回答」。
- ⚠️ **`ListAPI`（`/api/v1/user/{domain}/questions`）不经过 Pager 中间件**，L4 与页面密码必须自己校验。
- ⚠️ **整箱分享卡 `ShareCard` 与单题分享卡都要拦**，且拦截必须在缓存查询之前（否则 30 分钟内仍给旧图）。
- 举报 `POST /_/{domain}/{qid}/report`：免登录 + 验证码 + 限流；同 IP 同题唯一索引 →
**幂等且提示与首次一致**（否则成了内容存在性探测器）。箱主只看「被举报 N 次」，**不给 IP**。
- 闭环：删除/设私密/`hide-public` → `MarkAcceptedByQuestion`；待处理超 30 天视为过期。
⚠️ `hide-public` 里必须**先快照目标 ID 再更新**（更新后带 `is_private=false` 的子查询恒为空集）。
- 告警：24h≥8 或 7d≥20 → 邮件到 `[security] security_alert_email`（24h 冷却）；单条恰好 3 人举报 → 提醒箱主。
⚠️ 该邮箱为空时静默跳过、无日志；改配置必须重启。
- `/rules` 是处置依据页（四语言）；注册页必须勾 `agree_rules`（服务端同样校验），改 e2e 脚本要同步。
- `restrict`/`unrestrict` 默认给箱主发通知（按 `users.language`，`mail/restriction-notice.html`），
**只含级别名/到期/规则链接，不含 `--reason`**；`--no-notify` 跳过。`--days > 90` 要 `--force`。
⚠️ **到期自动解除不发信**（读表比较时间）。
## 蜜罐（2026-10-21）
- 落点是**改写 `f.NotFound`**（不是新中间件）：NotFound 只在路由表落空时触发 → 与业务路由零交集；
位于全局 Use 链之后（body 已限 12 MiB）；组级 CSRF 不作用于它。
- flamego 短路机制：`context.run()` 在 `ResponseWriter().Written()` 为真时 return → 写完响应不调 `ctx.Next()` 即止。
- 蜜罐命中的路径由蜜罐自己 `autoban.Record`，autoban 中间件须跳过（否则一次请求计两遍，阈值减半）。
- `HoneypotHit` 不嵌 `dbutil.Model`（审计证据只追加，不软删）。
- 假页只含 canary + 假信息；错误提示不区分「用户不存在」与「密码错误」（防用户名枚举）。
- 密码 CLI 默认脱敏；告警邮件含明文凭据 → 收件人只能是运维本人。
### 蜜罐封禁与 enable_auto_ban 解耦（2026-10-21 线上实测修复）
- ⚠️ **`Record()` 第一行 `if !b.enabled { return }` 会让 `enable_auto_ban=false` 连坐蜜罐** →
蜜罐只落库不封禁（实测命中 70+ 次零封禁）。已修：新增 `RecordHoneypot()` 独立通道 + 独立阈值/时长。
- `IsBanned()` 不得受 `enabled` 约束：`enabled` 只控制「是否主动创建封禁」，不控制「是否尊重已有封禁」。
- `RecordHoneypot` 的键必须与 `Record` 一致（同样 `shared.LimitKey` 归一化），否则 `IsBanned` 判不出来。
- 备份/配置/密钥泄露扫描（`/backup.zip`、`/db.sql`、`/id_rsa.pem`）文件名主体随机，**只有后缀稳定**
→ 用 `path.Base()` 后缀匹配表，不能只靠子串（`"/.zip"` 匹配不到 `/backup.zip`）。
### 蜜罐表体积与自动清理（2026-10-21）
- `honeypot_hits` 是**只追加**审计表，写入完全由外部扫描流量驱动（不可预期、不可节流）
→ 必须有自动保留期清理，否则表体积只增不减。
- 两道闸：时间（`honeypot_retain_days`）+ 数量（`honeypot_max_rows`）。数量闸不可省 ——
攻击者可用海量源 IP 在保留期内把表撑爆。
- ⚠️ PG 的 `DELETE` 只标记死元组，**表文件不会变小**；无 VACUUM 时表体积单调膨胀
（实测 22→52 MB）。清理后必须 `VACUUM (ANALYZE)`，但注意 **VACUUM 不缩小文件、
只让空间可复用**（止住增长即可，不必 `VACUUM FULL`）。
- ⚠️ `VACUUM` 不能在事务块/函数体内执行 → GORM 走 `Exec()`（Raw 处理器，不包事务）可行。
- ⚠️ 清理器的 `runOnce` 必须自己再挡一次 `retainDays<=0`，否则「保留 0 天」= 全删光。
- 索引：GORM 去掉 struct tag 的 `index` **不会**删既有库上的旧索引 → 需显式 DropIndex。
删索引前先用 EXPLAIN 确认零查询使用（`provider` 索引实测 10 万行 648 kB 且零使用）。
- CLI `honeypot size` 报告行数/磁盘占用/时间跨度 —— 把「有没有臃肿」交给运维自查。
.workbuddy/memory/topics/share.md
-58
View File
@@ -1,58 +0,0 @@
# 分享卡（share card）
两处入口都在 `route/question/share.go`：`ShareCard`（箱子卡，960×540）、`QuestionShareCard`（单题卡）。
单题卡出图条件：**已回答 + 非私密 + 无站方处置**（`db.Restrictions.ActiveLevel` 非空即拒绝，fail-closed）。
## 文字排版
- 居中/限宽**必须**用 `measureTextWidth`（逐字 `HMetric().AdvanceWidth` + `Kern`，`scale = fontSize*64`），
它与 `DrawString` 返回笔位逐位相等。绝不要用「中文 1em / 其余 em 系数」估算：URL 里的 `: / . _ -`
只有 0.25~0.35em，整句会虚高 55%，居中直接偏 40px。
- 链接展示走 `displayURL`（去 `https://`）→ `layoutLink`（单行 15→13px，放不下按 host/path 两行 13→11px，
host 超宽才中间省略，字号下限 `LinkMinSize`）→ `ellipsizeMiddle`。限宽恒定 `QRCardW-40`。
## 二维码（`generateQR`）
- **图像只输出符号**：`qr.DisableBorder = true`，静默区由承载它的白色卡片提供。
把 4 模块静默区画进图里 + 再居中留白，会让 165px 目标只剩 111px（3px/模块）——这是曾经的回归。
- `perModule = size / modules` 向下取整，符号 = `modules*perModule`；**调用方必须用 `qr.Bounds().Dx()`
排版与居中**，不能假设等于传入的 size。
- 单题卡 `QQRSize = 190`（37 模块 → 185px = 5px，卡片 236×300 居中于 679,120）；
箱子卡 `QRCodeSize = 190`（37 模块 → 185px = 5px，卡片 270×335）。
- 单题卡的二维码卡片绘制在 `drawQuestionQRCard`（handler 只是调用），测试可直接出图。
- 卡内垂直间距在 4px 栅格上：`24 / 17 / 20 / 1 / 20 / 16`，总高按链接行数算，整块垂直居中。
## 模块像素：唯一的硬指标
| 模块 | 960 | 720 | 480 | 320 | 240 |
|---|---|---|---|---|---|
| 4px（148px，37 模块） | o | o | **x** | x | x |
| 5px（185px，37 模块） | o | o | o | o | x |
（go-qrcode 纠错 Q、真实 55 字符链接、含内嵌头像；用 gozxing 解码，它比手机严格，可当保守下限。）
→ **目标 5px/模块**；`TestGenerateQRModuleSizeAtLeast5` 锁住三种常见链接长度，改小 QRCodeSize 立刻 FAIL。
改大模块的路线排序（成本从低到高）：
1. 同画布放大二维码（已做，0 CPU）——`generateQR` 只 0.8ms，与尺寸几乎无关。
2. 降纠错 Q→M：模块 37→33 只省 11%，容错 25%→15%，不划算，别单独用。
3. 换 PNG：只保住原图，缩到 480 一样解不出，体积还是 JPEG 的 5 倍。
4. 2x 渲染：+60~100ms（本地基准：JPEG 编码 12→48ms、背景 Lanczos 25→41ms、画布 3→13ms）。
只在「原图本身也要更精细（背景/文字抗锯齿）」时值得。
## 缓存命中率才是 2x 之外更值得看的地方
进程内 LRU 只有 16 条 + TTL 1h，站点箱子多时冷渲染频繁；把生成结果落盘 / 上 R2
能让「贵」只付一次。这是比 2x 更实在的优化方向。
## 验证手法
- 守门测试 `route/question/share_layout_test.go`：测量=笔位、链接限宽、按着墨边界判居中 ±3px、
二维码 `width == modules×perModule` 且吃掉目标尺寸 ≥80%、头像不在边缘裁切。改完都做变异验证。
- `TEST_PREVIEW=1 go test ./route/question/ -run TestShareCardLinkPreview` 出 270×315 的卡区域 PNG。
- 图片实测：PIL 数着墨 bbox（居中偏差 / 二维码宽度 / 各段间距）；解码用
`github.com/makiuchi-d/gozxing` 起个临时 module 跑（`_ "image/jpeg"` 和 `_ "image/png"` 都要 import）。
- 单题卡要真实出图：`.workbuddy/local/qcard_probe.py`（发提问 → 登录 → 回答 → 拉图 → 删除，不入库）。
## 缓存
进程内 TTL 1 小时 + 响应头 `Cache-Control: public, max-age=300`。改完要复验：重启（清进程内缓存）+ URL 加随机参数。
.workbuddy/memory/topics/stats.md
-134
View File
@@ -1,134 +0,0 @@
# 全站数据页（/stats）
2026-10 新增。完整数据在 `/stats`（公开、只读、纯服务端渲染）。
入口只有一处：**页脚「社区规则 | 数据 | 找站长」中间那格**
（`templates/base/footer.html`，词条 `site.footer.stats`）。
首页那张「站点统计」卡与后来的入口卡都已下线（用户明确要求首页不再放），
`route.Home` 也不再调 `stats.Get`；`/api/v1/site-stats` 接口保留未动。
新增入口不要再往首页加——那会让两处数字需要同步维护。
## 分层
```
db.Analytics.SiteAnalytics(ctx, now) // 纯 SQL 聚合，无缓存
→ stats.OverviewData(ctx) // 按自然日缓存（每天只算一次）
→ stats.NewPage(lang, ov) // i18n 标签 + 百分比 + 文字洞察
→ route.Stats → templates/stats.html
```
- `internal/db/analytics.go`：`SiteAnalyticsStore`。用 `SUM(CASE WHEN)` 而不是
`COUNT(*) FILTER`（MySQL 没有 FILTER）。方言差异（`to_char`/`DATE_FORMAT`、
`EXTRACT(DOW)`/`DAYOFWEEK-1`、`EPOCH`/`TIMESTAMPDIFF`）收敛在 `analyticsDialectFor`。
- `internal/stats/overview.go`：缓存 key 是**自然日字符串**，不是 TTL —— 换日即失效，
当天重算一次后全站共用。重算串行化（`ovRefresh`），失败时返回上一次成功的旧值。
- `internal/stats/page.go`：`Page` 嵌 `*Overview`。桶标签在 Go 侧拼好，别在模板里
`printf "stats.len.%s"` —— 缺词条会把 key 印到页面上。
- `internal/cmd/web.go`：启动后 3s 异步预热，把当天首访的等待挪出请求路径。
## 口径（改之前先看）
- 已回答 = `answer <> ''`；已读 = `is_read OR answer <> ''`。
- 匿名 = `asker_user_id = 0`；登录 = 总数 − 匿名。
- 回答耗时用 `answered_at - created_at`（**不是 updated_at**）。GORM 的 `Update`
会自动刷新 updated_at，已读/置顶/公开切换都走 Update —— 实测一条 10 天前的提问
被 `SetRead` 后 updated_at 直接推到当下。故新增 `questions.answered_at`（可空），
只在 answer 由空变非空时写一次，改写回答不重置；历史行为 NULL 时
`COALESCE(answered_at, updated_at)` 回退，且首次加列时用 updated_at 冻结一次
（`backfillAnsweredAt`，靠 `Migrator().HasColumn` 判断是否刚加列）。
- 环比是「上月 vs 上上月」，不是「本月 vs 上月」：本月没过完，每月 1 号会得出 -95%。
**句子必须点明月份与条数**：「9 月收到 5,620 条提问，比 8 月的 4,890 条多了 14.9%。」
不要写「上月提问量环比 -75.0%」——两个相对词（上月 / 环比）叠在一起，用户实测读成
「上月同期 vs 本月同期」。也不要用带符号的裸百分比（「环比 -75%」）当结论。
三套句式 `stats.insight.momUp/momDown/momFlat`（方向词进不了同一个模板，语法各语言不通）；
参数顺序统一是 本月份名/条数、对比月份名/条数、绝对值百分比，`|pct|<0.05` 走持平。
- 累计与图表是**当天重算一次**的快照（当天首访时算，重启也会重算；不是「0 点快照」），
「今日提问/回答」两项实时（60 秒 TTL，见下）。
- 页脚时间标签因此叫「快照时间」而不是「计算于」：它只覆盖累计与图表，
今日两项会被 `withToday` 换掉。原先另有「数据基准日」一行，与它是 100% 重复
（`Overview.DataDate` 就是 `UpdatedAt` 的日期部分），已删。
- 今日两项的 60s TTL **不要**为了省查询改成 30 分钟：每分钟最多 2 条 COUNT，
20 万行实测 38ms/条 → 最坏 109 秒 DB 时间/天（0.13%），换不到什么；
而 30 分钟会让「（实时）」变成假话、提问者自己看不见刚发的那条。
- 日/周/时分组必须在 SQL 里 `AT TIME ZONE INTERVAL '+08:00'` 显式换算，
不能依赖数据库会话时区 —— 见「时区」一节。
## 两个已踩过的坑（2026-10-24 部署前自查发现）
**1. 「今日」两项曾被每日缓存冻住。** 原先 `SiteAnalytics` 里查了今日数，塞进
`Overview`，而 `Overview` 整天复用 → 页面顶着「实时」的说明显示一整天不变的常量。
现在拆出 `SiteAnalyticsStore.TodayCounts`，`stats` 层单独 60 秒缓存（`todayTTL`），
跨日按日期字符串失效（`todayDate`）。缓存命中时返回的是**副本**（`withToday`），
不能原地改 `ovCached` —— 那是数据竞争。
**2. 日期分组默认跟着 PG 会话时区走，通常是 UTC。** PG 官方镜像 `timezone=UTC`，
而 Go 按容器本地时区（Dockerfile 设 Asia/Shanghai）切「今天」。实测同一条
`2026-10-24 01:30+08` 的提问：会话 UTC 下 `to_char` 给 `2026-10-23`、`EXTRACT(HOUR)` 给 17。
→ 日报表整体偏 8 小时（中国 0–8 点被算进前一天），热力图时段全错位，且与「今日」对不上。
现在 `analyticsLocalize()` 统一包一层 `AT TIME ZONE INTERVAL '+08:00'`，偏移取自
`time.Time.Zone()`（不用 IANA 名：Go 在未设 TZ 时给 "Local"，PG 不认）。
过滤条件仍是裸列，索引照用（EXPLAIN 确认走 Bitmap Index Scan）。
## 性能实测（20 万行 questions，本地 PG，冷缓存）
| 查询 | 耗时 | 扫描方式 |
|---|---|---|
| totals（全表条件聚合） | 337 ms | Seq Scan |
| 字数分布（全表） | 313 ms | Parallel Seq Scan |
| 热力图 180 天 | 100 ms | Bitmap Index Scan |
| 日趋势 30 天 | 47 ms | Bitmap Index Scan |
合计约 0.8 秒；1C1G 云机按 2–3 倍算约 2 秒。靠启动后 3 秒预热挪出请求路径，
可接受。**若 questions 到百万行**，三次全表扫描会到 6–10 秒，那时应把
totals + 字数分布 + 回答耗时合并成一条 SQL（都是同一张表的无条件 CASE 聚合，
合并后只扫一次）。现在不做：不知道真实表规模，每天只算一次，不值得为省 0.5 秒
把 SQL 拆成大块。
## 图表实现（零前端库）
站点为消除一个 1.6KB 外部 defer 就把页脚计时器内联了，这里不再挂 60KB 图表库。
- 折线：`NewLineChart` 一个函数给出 `{Max, Points, Area, Ticks}`，
SVG `viewBox` + `preserveAspectRatio="none"` + `vector-effect: non-scaling-stroke`
（否则窄屏描边被压细）。
- **坐标 / 面积 / 刻度必须同一次调用算出**：分开算会各按自己看到的峰值归一化，
线和刻度就错开半格。
- 纵轴上限 `niceMax(峰值)`（1/2/1.5/3/4/6/8×10^n），刻度 = 上限 / 一半 / 0；
上限恒为偶数 → 中间刻度必是整数。1.5 倍只在 mag≥100 时参与（否则是 7.5 半格）。
- 刻度文字放 SVG **外面**：viewBox 横向被拉伸，里面的文字会跟着变扁。
做法是左列绝对定位的 HTML 标签（top 用 Go 算好的 `TopPct`）+ 看不见的占位元素撑列宽。
- 面积沿基线（`h-padBottom`）闭合，别落到 viewBox 底边（那是轴标签的留白）。
- 全零/空数据只出轴不出线，否则贴基线的直线看着像「数据都是 0」。
- 柱状 / 分布条：`style="height:{{printf "%.1f" $pct}}%"`，CSS 直接用百分比。
- 环形：`<circle pathLength="100" stroke-dasharray="{{pct}} 100">` + `rotate(-90)`，
不用算周长。
- 热力图：CSS grid 24 列 + `aspect-ratio:1`，档位用 `--tb-primary` 的 opacity 分 4 档
（连续透明度在小方块上肉眼分不出来）。
- 7×24 的 DOW 下标：PG `EXTRACT(DOW)` 与 Go `time.Weekday()` 都是周日=0；
展示顺序（周一起）在 `weekdayOrder` 里转。
## 预览与验证
- `TEST_PREVIEW=1 go test ./templates -run TestGenPreview` 出
`outputs/preview-stats-{zh-CN,en}-{light,dark}.html`。
- `writePreview` 会把 `href="/static/` 换成本地相对路径 —— 不换的话预览页走 file://，
`:root` 令牌全缺，`var(--tb-*)` 变无效值：图表全透明、卡片没边框（一度以为是渲染 bug）。
- `internal/db/analytics_test.go` 连真库跑（`DB_TYPE=postgres ...`），验证软删除不计入、
各分桶下标、DOW 对齐。对着 mock 断言等于没验证。
- 窄屏别用 `chrome --window-size=390`：Windows headless 最小窗宽约 485，实测 innerWidth=485，
截图再裁到 390 就成了假的"溢出"。用 390px 宽 iframe 包一层再截。
## 隐私红线
公开页只给聚合数字。不显示 IP、不显示单条内容、不做箱主排行（会招骚扰）。
「收到过提问的箱子」这类计数可以，具体是谁不行。
## 文案（读者是访客，不是站长）
- 不写实现细节：缓存策略、懒重算、"服务重启也会重算"、索引、TTL —— 访客要的只是
「多久更新一次」。准确的新鲜度交给页脚「快照时间」那行。
- 不写作者视角的免责：「下面几句…没有推测」「本文」「这里只有」这类，读起来像在跟审稿人
解释，而不是在给访客看。已删 `stats.insight.note`。
- 确实要对访客交代的只有三件：数据来源/隐私（`stats.lead` + `stats.foot.privacy`）、
新鲜度（`stats.foot.cacheNote`）、口径例外（`stats.trend.monthlyNote` 的"当月还没过完"）。
- 删说明行会改变间距：`.tb-insights` 自己补 `margin-top`，别指望 `tb-card-note` 的 16px。
.workbuddy/memory/topics/style.md
-41
View File
@@ -1,41 +0,0 @@
# 前端样式（长版明细）
## 前端样式
- `static/css/base.css`（`?v=` 取 `conf.StaticVersion`，**改完必须 +1**）。令牌在 `:root`（亮）+
`html[data-theme="dark"]`（暗）。新样式一律 `var(--tb-*)`，别写死色值，也别为深色另写分支。
- 页面级样式内联在各自模板 `<style>`；尽量用类不用 `style=`（深色下内联写死色值会露白）。
- 主题属性在 head 内联脚本里打（cookie `theme`），**不能挪回 body**，否则深色用户白闪。
- **移动端（≤640px）语言切换与主题按钮在固定底栏** `#tb-mobile-utils`（`.tb-nav-utils` 被隐藏，
body 留 `padding-bottom:56px`）。用户曾误以为"按钮不见了"，先解释位置。
⚠️ `/_/{domain}` 箱主页 `IsUserPage = true`（`route/question/page.go:133`），语言切换包在
`{{ if not .IsUserPage }}` 里 → **箱主页没有语言切换入口，有意设计**（用户 2026-10-19 确认），别当 bug 修。
- ⚠️ **UIkit 3.3.3 的 `.uk-flex::before/::after{display:none}`**：给带 `uk-flex` 的元素加伪元素必须写
复合选择器（`.tb-cover.uk-flex::after`），否则静默失效。
- 分类/题型标签一律 `.tb-chip`；彩色 `uk-label` 只留给语义状态（置顶/私密/被举报/已读、投票四态）。
- **字号阶梯 5 档**：`--tb-fs-xs/md/lg/xl/hero`（12/14/16/24/28）。散落的 `.9/.95/.98rem` 一律映射到档位，
别新增第 6 个值。⚠️ 已令牌化的是模板层；`base.css` 自身仍留 11 处硬编码（0.78/0.82/0.88/0.95/1.1），
`templates/user/profile.html` 还留 16 处 —— 想彻底统一得先扫这两处。
- 圆角只用 `--tb-radius(-sm/-xs)`；`50%` 与 `999px` 是语义（头像、胶囊），**不要**换成令牌。
- ⚠️ `.uk-text-muted/.uk-text-meta` 必须带 `!important`：UIkit 3.3.3 自带 `color:#999!important`，
普通声明压不过（现象：规则写了但全站还是 #999）。
- **文字色下限 WCAG AA 4.5:1**（正文级）。`--tb-text-muted` = `#6b7280`（白底 4.83）。
旧值 `#8a919c` 3.18、`#999` 2.85 —— 肉眼"淡一点"其实已经不合格。
主色还没达标（`#1e87f0` 3.26 / `#4a7fc1` 3.69 / sakura `#e5678f` 2.80），要动得连主题一起改。
- ⚠️ **改 base.css 的配色令牌必须同步检查 `static/css/themes/*.css`**：主题覆盖同名令牌，
基座修了但主题页纹丝不动（sakura/shiroko 的 muted 就曾是 2.8:1，是这次才补到 4.6）。
- 顶栏链接：亮色用 `--tb-text-secondary`、hover/当前页 `--tb-primary`；深色块原本 `!important` 定成
`--tb-text`，会让同一顶栏在深浅两模式权重跳一档 → 已加 dark secondary 覆盖。
- **主色要达到 AA 4.5:1**（它同时是 14px 链接/按钮文字色）。现值：base `#0e6fd0`、shiroko `#3b6dac`、
sakura `#ba3e66`（都是同色相压亮度）。**改主色必须三处一起**：`base.css :root` + `themes/default.css` + 该主题。
- ⚠️ **`--tb-on-primary`**（亮 `#ffffff` / 暗 `#0b1016`）是「主色作背景时的文字色」。
深色模式的强调色偏亮（`#5c8dff`），白字只有 2.2~3.1:1 —— 用一个令牌同时伺候「链接色要深」和
「按钮底要深」是矛盾的，所以拆成两个。`.uk-button-primary`、`.uk-label:not(语义色)` 都吃它。
- 字号阶梯已全部落地（模板 + base.css）；`0.9em`（相对父级）、验证码等宽字形、`mail/*` 是**有意例外**。
- 视觉自检：`TEST_PREVIEW=1 go test ./templates -run TestGenPreview` → `outputs/preview-*.html`；
截图必须 `chrome --headless=old --force-device-scale-factor=1`（新版 headless 本机挂住）。
⚠️ `--window-size` ≠ CSS 视口；要精确视口就用 iframe 指定 width/height。验证 CSS 靠**像素比对**
（PIL 在 venv）而非目测；扫描循环上界不能与物体边界重合。
- ⚠️ **后台页不是都有卡片**：`/user/questions` 的列表是 `<hr>` 裸行，模板里唯一一处 `.uk-card`
是投票 tab 的标题条。默认主题 #fff 看不出来，换带整页插画的主题就"整页透上来"。
已在 `.qlist-panel` 上补卡片底；新增后台页时别假设外层已有卡片。
.workbuddy/memory/topics/theme.md
-67
View File
@@ -1,67 +0,0 @@
# 主题（箱主个性化）（长版明细）
## 主题（箱主个性化）
- 三个注入点：`/_/{domain}/*` → `question.Pager` 按 `pageUser.Theme`；`/user/*` → `internal/context`
Contexter 按 `c.User.Theme`（`isThemeScope()` 只认 `/user` 与 `/user/`）；`/vote/{token}` → `route/vote.Page`
按发布者 `owner.Theme`。都看箱主/发布者，不看访客。全站页（`/`、`/explore`、`/login`）不主题化。
- 投票页**语言**也跟发布者：`applyOwnerLocale(data, owner)`（与主题同一函数），必须在任何 i18n 取词之前调用。
- 一套主题 = `static/css/themes/<slug>.css`，**只覆盖令牌**，不碰布局。`static/fs.go` 已嵌整个 `themes/` 目录。
- 主题显示名：模板用 `{{ themeName .LangCode .Slug }}` → `theme.DisplayName`，i18n 没登记
`theme.name.<slug>` 时**回退成 slug**。⚠️ 别在模板里直接 `{{t .LangCode (printf "theme.name.%s" .Slug)}}`：
`i18n.T` 缺词条返回 key 本身，设置页就会显示 `theme.name.test01`（用户报过）。
- ⚠️ **`[theme] available` 是硬白名单，启动时读一次**：css 发布了但没登记，设置页看不到，现象同「部署没生效」。
排查：`curl /static/css/themes/<slug>.css` 200 = 文件在（没登记）；404 = 旧二进制。
- ⚠️ 主题 css **必须成对写**：`html[data-theme-style="x"]`(0,1,1) + `html[data-theme="dark"][data-theme-style="x"]`(0,2,1)。
`TestThemeCSSComplete` 查两个选择器 + 10 个颜色令牌。
- ⚠️ **按页面作用域**：`internal/context.pageScope()` → `<html data-page-scope>`，取值
`box`/`question`/`admin`(/user/questions,/user/votes*)/`profile`/`vote`。深色作用域覆盖必须**三重选择器**，
否则被浅色作用域块（同特异性、写在后面）盖掉。
- ⚠️ **装饰层固定 10 槽**（base.css 12 层 = pattern1 + deco10 + image1），三组 `--tb-deco/-size/-position`
必须等长。`TestDecoSlotCount` 逐文件逐声明检查（只扫 embed 到的文件）。
- 位置一律两值 `calc(0%|50%|100% ± N)`（百分比相对「容器 − 图片」）。**别用 left/bottom 关键字混搭**：
三值语法非法时整条声明作废 → 图层静默回左上。
- 尺寸想随视口缩用 `clamp`，**不要写死 px**：`auto clamp(min(calc(100vh - 24px), 231px), 46.67vh, 420px)`。
内层 `min()` 是兜底 —— 屏幕小到连下限都放不下时让位给视口。宽幅素材只能按宽度缩（`vw`），
按高度缩的话宽度按比例涨，窄屏照样裁。
- ⚠️ **UIkit 3.3.3 主色是编译期常量 `#1e87f0`**，令牌注入不进去。base.css 末尾按组件映射（a/uk-link、
uk-button-primary、checkbox/radio、input:focus、uk-tab active、`.uk-progress`、`.uk-label:not(...)`）。
- 令牌 `--tb-navbar`（顶栏底色，默认 `var(--tb-surface)`）：页面底色偏彩时主题必须覆盖。
⚠️ **顶栏只能半透明，不能全透明**（2026-10-22 用户明确要求）：装饰层从角落长出来时实色顶栏会把
花枝切一段；但改成 `transparent` 顶栏就"消失"了，导航失去依托、文字压在花纹上。正解是
`rgba(bg, 0.72)` + `.uk-navbar-container{backdrop-filter: blur(12px)}`（模糊只能写在规则里，
令牌只是颜色）。`TestNavbarNotFullyTransparent` 拦 `transparent` / `rgba(...,0)` / `#rrggbb00`。
同理 `#tb-mobile-utils` 在 base.css 里写死 `rgba(255,255,255,.92)`，彩色主题要自己调成同色系。
- ⚠️ 装饰层会穿过顶栏区域时，`top` 别停在 0~nav 高度内：改半透明后枝头会压到「登录」上
（700~760px 宽度实测），按顶栏高度（60 + margin 20）把 `top` 下移。
- 静态资源版本号统一 `conf.StaticVersion`；**图片不走这个缓存键**（`max-age=86400`），换图要给 URL 带 `?v=`。
- 整页背景 `--tb-page-image`（cover）/ `--tb-page-pattern`（平铺，`-size` 控尺寸）/ `--tb-page-position`
（焦点，默认 `var(--tb-page-position, center center)`，旧主题不写也不坏）。底色用**纯色**别用渐变；
图案 ≥24px、透明度 ≤0.06。
- ⚠️ **多背景层不能塞变量列表**：变量自身是逗号列表会让层数与 size/position 错位。多张装饰用固定槽位。
- 装饰摆位：**贴边、成组、避开页脚**；四角各摆一个会读成贴纸墙纸；页脚文案右对齐 → 右下角不能放人物。
`--tb-deco` 是 fixed 视口层，贴边插画别放进 `cover` 背景图（必裁边）。
- 主题视觉的**结构**比摆位重要：通行做法是「整屏场景插画 + UI 悬浮其上」（蔚蓝档案 JP）。
白底留白里摆人物，无论多大都读成贴纸；卡片/顶栏配半透明白 + `backdrop-filter` 才有"浮在画面上"的关系。
- 素材放 `static/images/themes/<slug>/`（embed 已含 `images/themes`，子目录自动覆盖）。整页图 16:9 + 竖版两张。
- 人物素材：**图生图 + 抠白底**（`image1` 给立绘、`input_fidelity: high`、`flat vector illustration, no outlines`）。
⚠️ 正面立绘直接贴进空场景像贴纸：改**侧后方视角**（不直视访客），RGB **压白 12~16%** 与压白 38% 的场景对齐雾度。
- ⚠️ **抠白底容差 16**：背景 253、白袜子 237 只差 16，容差 22 以上会把袜子吃穿。手内侧/两腿之间是
**闭合**白区，四边 floodfill 进不去，得按连通域单独掏（面积 ≥24），再 1px 收边。
- ⚠️ `ruleBody` 取令牌前要剥 `/* */`：注释会和后面的令牌粘成一个键，色块预览静默失效。
- ⚠️ **主题会覆盖 base.css 的同名令牌 —— 基座改配色必须同步改主题**。改 `--tb-text-muted` 时
sakura `#a08c94`(2.8:1)、shiroko `#8794a7`(2.76:1) 都还没跟上，"修了但主题页没变"就是这么来的。
现已调到 `#78696e`(4.61) / `#656e7a`(4.63)，深色块 `#a18790` / `#7f8ea1`（对压平后的卡片 4.62）。
主色也已修（`#0e6fd0` / `#3b6dac` / `#ba3e66`）+ 新增 `--tb-on-primary`，见 topics/style.md。
量对比度时半透明 `--tb-surface` 要**压平到 --tb-bg** 再算，别当纯白。
- 主题选择页的色块由浅色块的 `--tb-bg` + `--tb-primary` 生成（`swatchOf`），注释里别写令牌名。
- `test01` 是用户 2026-10-21 自建又删掉的验证主题（css + 2 张 webp 已移除，未提交）。
删主题只需删文件：`build()` 读不到 css 会打 warning 并忽略，已选该主题的用户静默回退站点默认。
`static/images/shiroko-cutout.png` 也一并删除（2026-10-21）：它从不进 embed，只是 docs 里的图生图参考图，
仓库不存这类大图。
- ⚠️ **白上白素材无法用颜色分开**：白底 + 白主体（如自行车）时，车身与背景是同一个白
（实测都 `#f9f9f9`），floodfill 只吃外圈，轮圈内/车架三角/车筐整块留下 = 看着"没抠干净"。
自检：`不透明像素里近白(>240) 占比`，正常应≈0（修复前 50%）。要么全部转透明（成品变线稿风），
要么重出绿幕/透明背景素材。细节见 `docs/theme-shiroko-assets-spec.md` 的「白上白」。
- ⚠️ 换 `props/*.webp` 时**不要裁画布**：`--tb-deco-size` 是 `auto 259px`，宽度按原图比例算，
裁完锚点 `left calc(50% - 612px)` 会漂；四周透明边留着不影响观感。
cmd/tamabox.go
-10
View File
@@ -22,16 +22,6 @@ func main() {
cmd.Web,
cmd.Censor,
cmd.Uid,
cmd.Ban,
cmd.Restore,
cmd.Reports,
cmd.Restrict,
cmd.Unrestrict,
cmd.HidePublic,
cmd.Honeypot,
cmd.Backup,
cmd.RestoreImages,
cmd.R2Outbox,
}
if err := app.Run(os.Args); err != nil {
logrus.WithError(err).Fatal("Failed to start application")
conf/app.sample.ini
+28 -286
View File
@@ -1,260 +1,57 @@
; ── 关于配置键名 ──────────────────────────────────────────────────────────
; ⚠️ 键名写错时，程序启动会 WARN 提示「存在无法识别的键」并给出最接近的合法键名。
; 对于少量已知的常见误拼（如 honeypot_retention_days → honeypot_retain_days），
; 程序会自动纠正并在日志里说明纠正了什么。
; 但请优先写对键名 —— 自动纠正只覆盖已知的误拼，不认识的键一律不猜。
[app]
production = true
; 【必填】站点对外访问地址。用于生成 og:url 与邮件中的全部链接
external_url = "https://box.shiroko.one"
external_url = "https://box.shiroko.one" ; 【必填】站点对外访问地址。用于生成 og:url 与邮件中的全部链接
; （找回密码、私信通知等），必须以 http(s):// 开头、结尾不带斜杠
; （程序会自动 TrimRight "/"）。域名迁移时只改这一处即可全局生效。
title = "NekoBox"
icp = ""
; 站点默认语言：zh-CN / zh-TW / en / ja，留空默认简体中文（访客未设置语言时的兜底）
default_lang = ""
default_lang = "" ; 站点默认语言：zh-CN / zh-TW / en / ja，留空默认简体中文（访客未设置语言时的兜底）
uptrace_dsn = ""
qiniu_access_key = ""
qiniu_access_secret = ""
aliyun_access_key = ""
aliyun_access_key_secret = ""
; 默认分享图背景图链接（1280x720）
share_background = "https://your-default-background.jpg"
; 分享卡绘图用的中文字体（相对项目根目录）。字体文件不在仓库里，必须自备一份，
; 否则分享卡接口会返回 500「字体文件未配置或无法加载」。可用 Noto Sans SC / 思源黑体，
; 支持 .otf/.ttf/.ttc；放好后无需重启生效。
font_path = "static/fonts/NotoSansSC-Regular.otf"
share_background = "https://your-default-background.jpg" ; 默认分享图背景图链接（1280x720）
font_path = "static/fonts/NotoSansSC-Regular.otf" ; 中文字体文件路径（相对项目根目录）
[security]
enable_text_censor = true
; 文本审核服务通道：qiniu（七牛）/ aliyun（阿里云）/ auto（七牛优先、阿里云兜底）。
text_censor_source = auto
; 留空等同于 auto，即引入该配置前的历史行为。
; 显式选 qiniu / aliyun 时必须在 [app] 配好对应凭据，否则启动即报错
; —— 避免运行期审核必然失败（审核失败是 fail-closed，拒绝提交，
; 会让发布/私信整站不可用，且现象隐蔽、只在日志可见）。
; 凭据位置：[app] 的 qiniu_access_key / qiniu_access_secret、
; aliyun_access_key / aliyun_access_key_secret。
; ⚠️ 配好凭据 ≠ 可用：阿里云通道走的是「内容安全 2.0 / 文本审核增强版」
; （接口 TextModeration，接入点 green-cip.cn-shanghai.aliyuncs.com），
; 开通前提只要求【实名认证，个人账号即可】，不需要企业认证。
; 开通入口：内容安全 2.0 控制台 → 开通「内容审核增强版」按量付费
; （开通本身不收费，按实际调用量出账；文本审核标准 7.5 元/万次）。
; 用 RAM 子账号调用需授予 AliyunYundunGreenWebFullAccess；欠费停服同理。
; 审核场景固定为 comment_detection（公聊评论检测，覆盖涉政/涉暴/涉黄等底线维度）。
; 单次 content 上限 600 字符，超长文本由代码分段审核（段间带重叠，避免跨段漏判）。
; ⚠️ 不要再去开通「内容安全 1.0」：它要求企业实名认证，个人账号无法开通，
; 调用会永久返回 code=596 "You have not opened Yundun Content Moderation Service"。
; 审核失败时日志会打印阿里云返回的 code / msg / requestId 便于定位；
; 首次出现账号级失败（未开通 / 未授权 / 密钥错误）还会额外打印一条一次性告警。
; 逗号分隔的IP黑名单，支持精确IP(如1.2.3.4)和CIDR(如1.2.3.0/24)，留空不启用
ip_blacklist =
; 黑名单IP访问时强制跳转到该URL
ip_blacklist_redirect_url =
; 是否信任反向代理设置的 CF-Connecting-IP / X-Real-IP / X-Forwarded-For 头。
trust_proxy = false
ip_blacklist = ; 逗号分隔的IP黑名单，支持精确IP(如1.2.3.4)和CIDR(如1.2.3.0/24)，留空不启用
ip_blacklist_redirect_url = ; 黑名单IP访问时强制跳转到该URL
trust_proxy = false ; 是否信任反向代理设置的 CF-Connecting-IP / X-Real-IP / X-Forwarded-For 头。
; 仅当站点部署在可信反向代理（如 nginx/Cloudflare）之后且代理已覆盖这些头时设为 true；
; 否则保持 false，防止客户端伪造 header 绕过速率限制与 IP 黑名单。
; ⚠️ 若站点在 Cloudflare 后且需使用下面的自动封禁，必须设为 true，
; 否则解析到的将是 Cloudflare 边缘 IP，自动封禁会误伤所有访客。
; ⚠️ 蜜罐取证同理：trust_proxy = false 时所有请求的来源都被记成反代地址
; （常见 127.0.0.1），取证数据失去意义；而且一次蜜罐封禁会连带封掉整站。
; 蜜罐命中回环地址时启动日志会打一次告警提醒检查这里。
; ⚠️ 开启 trust_proxy 时，必须配合「Cloudflare Tunnel / Authenticated Origin Pull /
; 防火墙仅放行 Cloudflare / EdgeOne 回源网段」锁定源站，否则攻击者可直连源站并伪造
; CF-Connecting-IP / EO-Client-IP 头。无需维护 CDN 庞大 CIDR 清单。
;
; —— 双 CDN（境内腾讯 EdgeOne + 境外 Cloudflare）场景 ——
; EdgeOne 回源会用 EO-Client-IP 携带客户端真实 IP（等效 CF-Connecting-IP），
; 本程序在 trust_proxy = true 时同时支持这两个权威头。
; ⚠️ 权威头只在「TCP 对端可信」时才被采信（回环地址，或命中 trusted_proxies）。
; 这条是代码里的硬约束，不再依赖运维纪律 —— EdgeOne 不剥离客户端自带的 CF-Connecting-IP，
; 旧实现无条件优先读它，导致经 EdgeOne 进来的请求客户端 IP 完全可控：
; 限流 / IP 黑名单失效，且 autoban 按假 IP 记账可被用来栽赃任意正常用户。
; 双 CDN 并存时：① 两家回源网段都登记到 trusted_proxies；② 防火墙仅放行两家回源网段；
; ③ 仍建议在各家规则引擎里删掉「对方 CDN」的权威头（纵深防御）。
; 仅用 cloudflared Tunnel 回本机时对端是 127.0.0.1，无需任何额外配置。
; 重新启用 EdgeOne 前请先按本节核对，步骤见 outputs/edgeone-cloudflare-dual-cdn-guide.md。
; 本程序在 trust_proxy=true 时已同时信任这两个权威头。
; 两家 CDN 并存时必须：① 防火墙仅放行两家回源网段；② 在各家 CDN 的规则引擎中
; 删除回源请求里「对方 CDN」的权威头（经 EdgeOne 回源删 CF-Connecting-IP、
; 经 Cloudflare 回源删 EO-Client-IP），否则攻击者可借道另一家伪造客户端身份，
; 绕过限流 / 自动封禁 / 单 IP 投票限制。详细步骤见 outputs/edgeone-cloudflare-dual-cdn-guide.md。
trusted_proxies =
; 逗号分隔的「你自己的」反向代理/负载均衡 IP 或 CIDR（如 10.0.0.0/8），
; 或「CDN 直连回源」形态下该 CDN 的回源网段。
; 回环地址（127.0.0.1 / ::1）无需登记即视为可信对端：cloudflared / 本机 nginx
; 回源的连接必然由本机进程发起，外部无法伪造。
; 除回环以外，CDN 权威头也必须对端命中本清单才会被采信 —— 公网对端带来的
; CF-Connecting-IP / EO-Client-IP 一律忽略，改用 TCP 对端地址。
; 仅当 TCP 对端命中本清单时才解析 X-Forwarded-For / X-Real-IP。
; 注意：此清单用于你自己的基础设施（含你选定 CDN 的回源网段），
; 不是 CDN 的全量 CIDR 清单。
; 内容安全策略（CSP）模式：off / report / enforce，留空等同 report。
csp = enforce
; enforce（默认）：真正拦截。脚本白名单由代码从 [upload] 的图片 CDN 域名与
; [recaptcha] 的域名自动派生，另内置模板实际引用的 cdnjs.snrat.com
; （UIkit/Alpine/dayjs/vConsole）、challenges.cloudflare.com 与 umami 统计域；
; 配了 sentry_dsn 时自动放行 browser.sentry-cdn.com。
; ⚠️ 日后新增第三方脚本 / 字体 / 接口域名，必须同步加进 internal/route/csp.go，
; 否则控制台会刷 "Refused to load ..." 且对应功能静默失效。
; report：只下发 Content-Security-Policy-Report-Only，页面照常加载，违规只进浏览器
; 控制台（配了 csp_report_uri 才上报）。不给上报地址时它等于没装，
; 所以只在「怀疑误伤、想先看证据」时临时用。
; off：完全不下发（排障逃生口）。
; 默认值的前提是白名单已用真浏览器逐页巡检过：
; outputs/sec-audit-2026-10-25/csp_sweep.py（20 个页面零违规）。
; 上线后发现误伤：把这里改成 report 或 off 再重启，不用改代码。
; 图片 / 样式 / 字体 / 连接放宽到 https:（箱主上传图与主题背景可能落在任意 CDN），
; 真正收紧的是 script-src、object-src、base-uri、form-action、frame-ancestors。
; report：只下发 Content-Security-Policy-Report-Only，页面照常加载，违规只进浏览器
; 控制台（配了 csp_report_uri 才上报）—— 用于上线前观察一周再切 enforce。
; enforce：真正拦截。脚本白名单由代码从 [upload] 的图片 CDN 域名与 [recaptcha] 的域名
; 自动派生，另内置模板实际引用的 cdnjs.snrat.com（UIkit/Alpine/dayjs/vConsole）
; 与 challenges.cloudflare.com。
; ⚠️ 日后新增第三方脚本 / 字体 / 接口域名，必须同步加进 internal/route/csp.go，
; 否则控制台会刷 "Refused to load ..." 且对应功能静默失效。
; off：完全不下发（排障逃生口）。
; 图片 / 样式 / 字体 / 连接放宽到 https:（箱主上传图与主题背景可能落在任意 CDN），
; 真正收紧的是 script-src、object-src、base-uri、form-action、frame-ancestors。
; CSP 违规上报地址（可选）。留空时违规只进浏览器控制台，不上报。
csp_report_uri =
; ⚠️ 限流与自动封禁的计数器都在进程内存里（internal/route/ratelimit.go、
; internal/security/autoban）。单副本部署（当前形态：cloudflared Tunnel 回一台机器）
; 下工作正常；一旦改成多副本 / 多机，每个副本各有一份计数（实际额度 × 副本数），
; 进程重启即清零。多副本前必须先把计数迁到 Redis。
; 封禁「事实」已落库（ban_records 表：键 / 原因 / 时长 / 到期时间），
; 重启丢的只是生效状态，账本还在。
enable_auto_ban = true
; 是否把「未注册路径的 404」计入封禁统计（默认 false）。正常业务
ban_track_notfound = false
; 逗号分隔的「你自己的」反向代理/负载均衡 IP 或 CIDR（如 127.0.0.1、
; 10.0.0.0/8）。仅当 TCP 对端落在该清单内时才解析 X-Forwarded-For / X-Real-IP。
; 留空（默认）则这两个头永不被信任，仅采用 CDN 权威头 CF-Connecting-IP /
; EO-Client-IP（需源站已锁定）。
; 注意：此清单用于你自己的基础设施，不是 CDN 的全量 CIDR 清单。
enable_auto_ban = true ; 自动封禁（fail2ban 风格）：检测到批量扫描/探测后临时封禁来源 IP
ban_track_notfound = false ; 是否把「未注册路径的 404」计入封禁统计（默认 false）。正常业务
; （域名/题目不存在等均走 302 业务跳转，不产生 404 计数）一律放行，
; 仅命中后台扫描特征路径（/admin、/.env 等）才参与统计封禁，避免
; 共享出口（CDN 边缘 / CGNAT）下正常用户被 404 探测连坐误伤。
; 如需恢复对纯 404 字典扫描的封禁再置 true。
; 统计窗口内命中敏感路径（/admin、/.env、/wp-admin 等）的次数阈值
ban_threshold_sensitive = 10
; 统计窗口内返回 404 的次数阈值（仅 ban_track_notfound = true 时生效）
ban_threshold_404 = 20
; 统计窗口时长（秒）
ban_window_seconds = 60
; 临时封禁时长（分钟），到期自动解除，重启即清零
ban_duration_minutes = 15
; 触发封禁时发送告警邮件的收件人（复用下方 SMTP 发信配置），留空不发送。
; ⚠️ 也是蜜罐告警邮件收件人，而蜜罐邮件正文含**明文账号密码**：
; 必须是个人邮箱，禁止填群组 / 分发列表 / 团队共用邮箱。
security_alert_email =
; ── 蜜罐（虚假后台登录界面）────────────────────────────────────────────
; ⚠️ 本段一律「注释独占一行、值单独一行」。
; 配置加载器开启了 IgnoreInlineComment，行尾 `; 注释` 会**并入值**：
; honeypot_max_rows = 200000 ; 说明 → 值变成 "200000 ; 说明" → int 解析失败
; honeypot_paths = ; 说明 → 值变成 " ; 说明" → 被切成一堆假路径
; 后果是该项静默回退零值，而日志里只会说「配置值不对」，很难联想到是注释造成的。
; 本文件其余段落已全部改成这个写法，新增配置项时请保持一致。
; 开启后，扫描器探测后台路径（/wp-admin、/.ssh、/.env 等）时不再返回 302，
; 而是返回一个仿 WordPress 的假登录页，并把其提交的用户名/密码写入取证文件。
; 只在「没有任何路由匹配」的路径上生效，真实业务路由零交集。
; 假页面只含 canary 标记与假表单，绝不含任何真实信息。
enable_honeypot = false
; 追加自定义诱饵路径（逗号分隔），与内置清单取并集。留空 = 只用内置清单。
; 用 `TamaBox honeypot paths` 可查看最终生效的完整清单。
honeypot_paths =
; 蜜罐命中记录的保留天数（取证用途），到期自动清理。
; ⚠️ 键名是 honeypot_retain_days（没有 tion）。写错会被静默忽略，
; 程序会尝试自动纠正并在日志里提示，但别指望它每次都猜对。
; 缺省 30 天；写 0 或负数会回退 30（不表示「永不清理」）。
; 要关闭自动清理请用 honeypot_auto_clean = false。
honeypot_retain_days = 30
; 是否启用蜜罐记录的后台自动保留期清理（每小时一轮）。
; honeypot_hits 是只追加的审计表，写入完全由外部扫描流量驱动，
; 不清理的话表体积只增不减。关闭后仍可手动 `TamaBox honeypot prune`。
honeypot_auto_clean = true
; 蜜罐命中记录的行数上限（第二道闸）。显式写 0 = 不限（会告警提醒表只增不减）。
; 保留期是时间维度上界，但攻击者可用海量源 IP 在保留期内把表撑爆。
; 实测单行约 281 字节（含索引，常规 UA），20 万行约 53 MB。
honeypot_max_rows = 200000
; 「提交凭据」多少次即封禁。默认 1（一次即封）：往假后台里填账号密码是证据最强
; 的行为，抓到一次就足够。⚠️ 不作用于纯 GET 探测 —— 那类请求走 ban_threshold_sensitive，
; 否则扫描器看一眼假登录页就被封，永远走不到提交凭据那一步。
honeypot_threshold = 1
; 蜜罐封禁时长（分钟）。缺省 1440（24 小时），刻意远长于 ban_duration_minutes：
; 命中蜜罐意味着对方已在提交账号密码，证据强度远高于单纯路径探测。
; 显式写 0 = 回退 ban_duration_minutes。
; ⚠️ 蜜罐封禁与 enable_auto_ban 相互独立：即使关掉自动封禁，
; 只要 enable_honeypot = true，蜜罐命中仍会封禁并记录。
honeypot_ban_minutes = 1440
; 凭据取证文件的存放目录。
; ⚠️ 捕获到的用户名/密码**不入库**，只追加到这个目录下的按天文件
; （creds-YYYY-MM-DD.jsonl，一行一条 JSON）。原因：明文账号密码一旦入库，
; 就会跟着进备份、主从复制和任何能连库的报表工具，事后无法彻底清除。
; 目录会被强制为 0700、文件 0600；相对路径以进程工作目录为基准。
; 目录不可写时只降级为「不保存凭据」，不影响站点启动。
; 建议单独挂一个卷，并让它不参与备份。
honeypot_cred_dir = data/honeypot-creds
; ── 安全状况汇总报告（周报 / 月报）──────────────────────────────
;
; 把周期内的蜜罐命中按来源 IP 聚合，再通过公共 IP 库定位到城市，
; 生成「世界地图 + 国家/城市排行 + 来源明细」的 HTML 报告并邮件送达。
;
; ⚠️ 与 cdncheck 离线指纹的区别：那个只认云厂商 / CDN / WAF 的 ASN，
; 肉鸡（家宽、企业宽带、移动网络）一律显示「未识别（普通网络）」。
; 下面的 IP 库回答的是「这个 IP 在哪儿」，是另一个维度。
;
; 数据源（ip_geo_provider）：
; auto（缺省） = ip-api.com 批量打底（全球、无需 key）+ 腾讯精修国内
; ipapi = 只用 ip-api.com
; tencent = 只用腾讯位置服务（必须配 key，否则降级 ipapi）
; none = 不查询任何外部服务，攻击者 IP 一个字节都不外发
; 隐私边界：auto / ipapi 会把攻击者 IP 发给 ip-api.com，tencent 发给腾讯。
ip_geo_provider = auto
; 腾讯位置服务 key（lbs.qq.com 申请，个人免费额度足够）。
; 两个用途：① 精修国内 IP 的省市与坐标；② 报告里可交互地图的底图。
; 留空 → 跳过国内精修，报告里只保留离线地图（经纬网 + 气泡）。
ip_geo_tencent_key =
; 周期性安全汇总邮件。缺省全开。
; 发送时机：周报在每周一、月报在每月 1 日之后的第一轮检查发出，覆盖
; 「上一个完整周期」；服务停机错过时间窗会在重新上线后补发；
; 幂等由 security_report_logs 的 period_key 唯一索引保证，不会重复发。
; 失败最多重试 5 次后停下（SMTP 配错时无限重试只会刷满日志），
; 之后可用 TamaBox honeypot report 手动补发。
honeypot_report_enabled = true
honeypot_report_weekly = true
honeypot_report_monthly = true
; 报告收件人。留空回退 security_alert_email。
; 单独一个键是为了能把「随时发生的封禁告警」与「定期汇总」分投到不同邮箱
; （例如告警进手机推送邮箱、汇总进归档邮箱）。
honeypot_report_email =
; 报告文件（HTML + PNG）的存放目录，按 0700 创建、文件 0600。
; 里面有攻击者 IP 明细，不要放进 Web 可访问的目录。
; 想先看内容不发送：TamaBox honeypot report --period week --no-email
honeypot_report_dir = data/reports
; 被封禁（自动封禁 / 蜜罐封禁）时返回的图片路径，相对路径以进程工作目录为基准。
; 留空、文件读不到、或内容不是图片 → 一律回退为纯文字 "403 Forbidden"。
; 只接受 image/* 的内容（png / jpeg / gif / webp）：指向 app.ini 之类会被拒绝，
; 否则等于把配置文件当响应体吐给攻击者。
; 建议用 256×256 左右的图并压到 20 KB 以内 —— 被封的来源会反复重试，
; 每张图都会照常占用出网带宽。
ban_image_path =
; 站点默认「内容审核严格度」：lax（宽松）/ standard（标准）/ strict（严格）。
default_moderation_strictness =
; 仅对未单独设置档位的账号生效（账号在设置页选择后以账号设置为准）。
; 留空回退 strict（最严档）：保证升级不会放宽任何拦截。
; 严格档是三个档位中最严的（拦截面不小于升级前），因此部署后默认拦截面可能略有扩大；
; 若希望默认更少误伤，改为 standard 即可，无需改代码。
; 三档的拦截范围见 internal/security/censor/policy.go，
; 适用于提问、投票、私聊三类内容。
ban_threshold_sensitive = 10 ; 统计窗口内命中敏感路径（/admin、/.env、/wp-admin 等）的次数阈值
ban_threshold_404 = 20 ; 统计窗口内返回 404 的次数阈值（仅 ban_track_notfound = true 时生效）
ban_window_seconds = 60 ; 统计窗口时长（秒）
ban_duration_minutes = 15 ; 临时封禁时长（分钟），到期自动解除，重启即清零
security_alert_email = ; 触发封禁时发送告警邮件的收件人（复用下方 SMTP 发信配置），留空不发送
[server]
port = 80
@@ -265,6 +62,8 @@ listen =
salt = ""
# ⚠️ 必填：密码哈希盐，留空会导致启动失败（已在 conf.Init 强制校验）
xsrf_key = ""
# ⚠️ 必填：CSRF token 密钥，留空会导致启动失败（已强制校验）
xsrf_expire = 3600
[database]
type = "postgres"
@@ -282,8 +81,7 @@ addr = "127.0.0.1:6379"
password = ""
[recaptcha]
; recaptcha（默认）, turnstile, math（本地算数验证码，国内访问友好）
captcha_type = recaptcha
captcha_type = recaptcha ; recaptcha（默认）, turnstile, math（本地算数验证码，国内访问友好）
domain = "https://www.recaptcha.net"
site_key = ""
server_key = ""
@@ -318,19 +116,6 @@ password = ""
port = 465
smtp = ""
[notify]
; ── 站级广播式通知通道（可选，均留空则只走 [mail] 点对点邮件）──────────────
; webhook_url：通用 Webhook（Discord / Slack / 企业微信群机器人等），站级事件
; （新提问 / 新回答 / 新追问 / 新私聊 / 新投票回复）统一 POST JSON 推送。
; 留空 = 不推送站级 Webhook。
; 注意：不同平台的 webhook 格式不同，这里发送统一 JSON（含 content/event/title/
; body/link/time 字段），Discord 可直接用 content 字段展示；其他平台建议在
; webhook 前端加一层转发做格式适配。
; webhook_url = ""
; telegram_bot_token：Telegram Bot token，配合每个箱主自填的 Chat ID 实现
; 「新提问」点对点通知。留空 = 禁用 Telegram 通知。
; telegram_bot_token = ""
[limits]
; ── 全站内容 / 数量上限（运行时配置，修改后重启生效）──────────────────────
; 缺失本段或个别键时按内置默认值运行。长度统一按字符（rune）计数。
@@ -370,46 +155,3 @@ chat_message_len = 2000
chat_max_messages = 200
; 单用户每日私信条数上限（用户可设范围 0..该值；0 表示不限制每日条数）
daily_message_limit_max = 999
[announcement]
; ── 站内公告：全站每页导航栏下方展示，改完重启生效 ──────────────────────
; content ：默认文案，留空 = 关闭公告（任一语言文案非空也视为开启）。
; 用 \n 表示换行；http(s) 地址会自动变成链接；
; 内容按纯文本渲染，不支持 HTML 标签（写 <b> 会原样显示）。
; content_zh_cn / content_zh_tw / content_en / content_ja：
; 分语言文案，留空则回退到 content；content 也留空时该语言不显示公告。
; timezone：start / end 里不带偏移的「裸时间」按哪个时区解释，默认 Asia/Shanghai。
; 可填任意 IANA 时区名（UTC / America/New_York …）；二进制已内嵌 tzdata，
; 容器不需要另装时区包。带偏移的 RFC3339 以自带偏移为准。
; start / end：展示时间窗，左闭右开 —— 到 end 那一刻下线。留空表示该侧不限：
; 只写 start = 定时上线；只写 end = 现在起展示到某时刻；都留空 = 一直展示。
; 支持 2026-10-25 02:00 / 2026-10-25 02:00:59 / 2026-10-25 / RFC3339
; （2026-10-25T02:00:00+08:00）。
; 时间或时区写错不会导致启动失败：日志 WARN 后关闭公告。
; 例：content = "10 月 25 日 02:00–04:00 机房维护，期间可能短暂无法访问。详情见 https://status.shiroko.one"
; content_en = "Maintenance 02:00-04:00 on Oct 25 (UTC+8). Details: https://status.shiroko.one"
; start = "2026-10-24 00:00"
; end = "2026-10-25 04:00"
content = ""
content_zh_cn = ""
content_zh_tw = ""
content_en = ""
content_ja = ""
start = ""
end = ""
timezone = Asia/Shanghai
[theme]
; 主题系统：只改配色 / 图案 / 整页背景，不涉及布局。
; 作用范围：提问箱页面（主页 / 单题 / 密码 / 分享卡）、箱主本人的投票页与 /user 后台；
; 首页、探索等站方页面保持站点默认外观。
; default ：站点默认主题（箱主未选择时使用）。填 default 或留空 = 现有外观。
; available ：启用哪些主题，逗号分隔，同时是箱主设置页的白名单；
; 列了但 static/css/themes/<slug>.css 不存在的会被忽略并告警。
; 新增主题：把 static/css/themes/_scaffold.css 复制成 <slug>.css，
; 改选择器与令牌值，再把 <slug> 加进 available —— 不需要改模板。
; 需要图片素材的，放 static/images/themes/<slug>/（static/fs.go 已嵌 images/themes 目录）。
default = default
available = default,sakura,shiroko,new-sakura
; ⚠️ 没登记在 available 里的主题，即使 css 已随二进制发布也不会出现在设置页；
; 启动日志会打出「[theme] available 未登记以下主题」提醒。
dev/devcheck-restrict.sh
-149
View File
@@ -1,149 +0,0 @@
#!/usr/bin/env bash
# 处置链路部署后自检（L1 停止分发 / L4 整页停用 / CLI 可用性）
#
# 为什么需要它：本机沙箱起不了 web（无 redis），L1/L4 的 HTTP 行为只能在服务器上验证。
# 这个脚本把「施加处置 → 观察 HTTP → 自动撤销」串起来，避免手工操作忘了解除。
#
# 用法：
# BASE_URL=https://box-dev.example.com DOMAIN=<测试箱主域名> TAMABOX=/path/to/NekoBox \
# bash dev/devcheck-restrict.sh # 只打印将要执行的命令（dry-run）
#
# BASE_URL=... DOMAIN=... TAMABOX=... RUN=1 \
# bash dev/devcheck-restrict.sh # 真正执行，结束时自动撤销
#
# 注意：
# - DOMAIN 必须是**测试箱主**，不要用真实用户；脚本会临时施加 L4/L1 再撤销。
# - 站点默认语言可能是 ja，页面文案断言按日文/英文各查一次，避免误判「没生效」。
# - 只依赖 CLI 与 curl，不需要 psql 凭据。
set -uo pipefail
BASE_URL=${BASE_URL:?need BASE_URL, e.g. https://box-dev.example.com}
DOMAIN=${DOMAIN:?need DOMAIN, a TEST box domain only}
TAMABOX=${TAMABOX:-./NekoBox}
RUN=${RUN:-0}
DAYS=${DAYS:-1}
pass=0
fail=0
restricted=0
say() { printf '%s\n' "$*"; }
check() {
local name=$1 want=$2 got=$3
if [ "$want" = "$got" ]; then
say " PASS $name (=$got)"
pass=$((pass + 1))
else
say " FAIL $name (want $want, got $got)"
fail=$((fail + 1))
fi
}
code() { curl -s -o /dev/null -w '%{http_code}' --max-time 10 "$1"; }
do_restrict() {
restricted=1
if [ "$RUN" = 1 ]; then
"$TAMABOX" restrict --domain "$DOMAIN" --level "$1" --days "$DAYS" --reason "deploy self-check" --yes
else
say " [dry-run] $TAMABOX restrict --domain $DOMAIN --level $1 --days $DAYS --reason 'deploy self-check' --yes"
fi
}
cleanup() {
if [ "$RUN" = 1 ] && [ "$restricted" = 1 ]; then
say ""
say "== 兜底撤销（无论中途是否失败）=="
"$TAMABOX" unrestrict --domain "$DOMAIN" || true
fi
}
trap cleanup EXIT
say "== 0. 二进制是否包含新命令 =="
if "$TAMABOX" --help 2>&1 | grep -q 'restrict'; then
say " PASS restrict 命令存在"
pass=$((pass + 1))
else
say " FAIL 二进制里没有 restrict —— 构建的是旧代码（注意入口是根目录 tamabox.go，或用 ./cmd/）"
fail=$((fail + 1))
say ""
say "结果: 无法继续，先修构建入口。"
exit 1
fi
say ""
say "== 1. 基线：处置前箱主页必须可访问 =="
base=$(code "$BASE_URL/_/$DOMAIN")
if [ "$base" != 200 ]; then
say " FAIL 基线不是 200（got $base），后续断言全部无意义，已中止。"
say ""
say " 302 的常见原因（按概率排序）："
say " 1) 域名不存在或账号已停用 —— 先确认 DOMAIN 拼写。查一个真实域名："
say " curl -s $BASE_URL/explore | grep -o 'href=\"/_/[^\"]*\"' | head -5"
say " 或在库上执行：select domain from users where deleted_at is null order by id desc limit 5;"
say " 2) 该箱主设置了页面密码 —— 此时首页是 200（渲染密码页），不是 302。"
say ""
say " 注意：302 不能证明任何处置生效。上次自检就出现过「箱主不存在 → 302」被误判成 L4 生效。"
exit 1
fi
say " PASS box page = 200"
say ""
say "== 1b. 停用页是否部署（与处置无关，dry-run 也验）=="
check "restricted page reachable" 200 "$(code "$BASE_URL/restricted")"
body=$(curl -sL --max-time 10 "$BASE_URL/restricted")
if printf '%s' "$body" | grep -qE '一時的に利用できません|temporarily unavailable|暫時無法存取|暂时不可访问'; then
say " PASS restricted page copy rendered"
pass=$((pass + 1))
else
say " FAIL restricted page copy not found（i18n 或模板没部署上）"
fail=$((fail + 1))
fi
if [ "$RUN" != 1 ]; then
say ""
say "== dry-run：不做状态断言 =="
say " 状态没有被改动，断言 L4/L1 只会得到误导性结果。"
say " 基线已确认可访问，用 RUN=1 重跑以执行真实验证："
say " RUN=1 BASE_URL=$BASE_URL DOMAIN=$DOMAIN TAMABOX=$TAMABOX bash $0"
exit 0
fi
say ""
say "== 2. L4 整页停用 =="
do_restrict L4
sleep 1
check "box page under L4" 302 "$(code "$BASE_URL/_/$DOMAIN")"
say ""
say "== 3. L1 停止分发：页面恢复、分享卡被拦 =="
do_restrict L1
sleep 1
check "box page under L1" 200 "$(code "$BASE_URL/_/$DOMAIN")"
qid=$(curl -s --max-time 10 "$BASE_URL/_/$DOMAIN" | grep -o "/_/$DOMAIN/[0-9]\+" | head -1 | grep -o '[0-9]\+$')
if [ -n "${qid:-}" ]; then
check "share card under L1 (qid=$qid)" 302 "$(code "$BASE_URL/_/$DOMAIN/$qid/share-card")"
else
say " SKIP 该箱主没有已公开回答，无法验证分享卡（换一个有已答问题的测试箱主）"
fi
say ""
say "== 4. 撤销 =="
if [ "$RUN" = 1 ]; then
"$TAMABOX" unrestrict --domain "$DOMAIN"
restricted=0
check "box page after unrestrict" 200 "$(code "$BASE_URL/_/$DOMAIN")"
else
say " [dry-run] $TAMABOX unrestrict --domain $DOMAIN"
fi
say ""
say "== 结果: PASS=$pass FAIL=$fail =="
if [ "$fail" -gt 0 ]; then
say "有失败项，把上面输出 + 服务日志（journalctl / docker logs 里搜 'Failed to query user restriction'）一起发我。"
exit 1
fi
say "全部通过。仍需人工手测两项：L2（回答应保存为私密）、L3（回答应被拒绝）。"
dev/gofmt_keep_crlf.py
-63
View File
@@ -1,63 +0,0 @@
#!/usr/bin/env python3
# dev/gofmt_keep_crlf.py
#
# 运行 gofmt -w，但保留文件原始行尾（CRLF / LF），避免 gofmt 把 CRLF 文件整文件
# 重写成 LF 造成的万行级 diff 污染。
#
# 用法：
# python dev/gofmt_keep_crlf.py <file1> [file2 ...]
# git diff --name-only | grep '\.go$' | xargs python dev/gofmt_keep_crlf.py
#
# 实现要点：先把源文件按 LF 写入临时副本交给 gofmt，gofmt 输出也是 LF；
# 若原文件是 CRLF，再把输出整体换回 CRLF 写回，从而只保留真实的格式化改动。
import os
import sys
import subprocess
GOFMT = r"C:/Program Files/Go/bin/gofmt"
def fmt_one(path):
with open(path, "rb") as f:
data = f.read()
crlf = b"\r\n" in data
tmp = path + ".gofmt.tmp"
with open(tmp, "wb") as f:
f.write(data.replace(b"\r\n", b"\n"))
try:
r = subprocess.run([GOFMT, "-w", tmp], capture_output=True)
if r.returncode != 0:
sys.stderr.write(
"gofmt FAILED on %s:\n%s\n" % (path, r.stderr.decode("utf-8", "replace"))
)
return False
with open(tmp, "rb") as f:
out = f.read()
finally:
try:
os.remove(tmp)
except OSError:
pass
if crlf:
out = out.replace(b"\r\n", b"\n").replace(b"\n", b"\r\n")
with open(path, "wb") as f:
f.write(out)
return True
def main():
files = [a for a in sys.argv[1:] if a.strip()]
if not files:
sys.stderr.write("usage: gofmt_keep_crlf.py <file> [file ...]\n")
return 2
ok = True
for p in files:
if not fmt_one(p):
ok = False
return 0 if ok else 1
if __name__ == "__main__":
sys.exit(main())
dev/overlay.json
+1 -1
View File
@@ -1 +1 @@
{"Replace": {"C:/OtherFiles/Github/TamaBox-v4-mainline/internal/storage/s3.go": "C:/OtherFiles/Github/TamaBox-v4-mainline/dev/s3stub/s3_stub.go"}}
{"Replace": {"C:/OtherFiles/Github/TamaBox-v4-mainline/internal/storage/s3.go": "C:/Users/TAMAKY~1/AppData/Local/Temp/tamabox_s3_stub.go"}}
dev/preview-honeypot/main.go
-77
View File
@@ -1,77 +0,0 @@
// Command preview-honeypot 把全部伪装家族渲染成静态 HTML，供人工核对外观。
//
// 用法：go run ./dev/preview-honeypot
// 产物：outputs/honeypot-preview/index.html（9 个 iframe 并排）
//
// 改动 internal/security/honeypot/family.go 的皮肤后重新跑一次，
// 比对着源码想象 CSS 可靠得多 —— 上一版就是靠它发现 Tomcat 按钮没背景色。
package main
import (
"fmt"
"os"
"path/filepath"
"strings"
"github.com/tamakyi/TamaBox/internal/security/honeypot"
)
type item struct {
fam honeypot.Family
action string
note string
}
func main() {
dir := "outputs/honeypot-preview"
if err := os.MkdirAll(dir, 0o755); err != nil {
panic(err)
}
items := []item{
{honeypot.FamilyWordPress, "/wp-login.php", "/wp-login.php · /wp-admin"},
{honeypot.FamilyPhpMyAdmin, "/phpmyadmin/index.php", "/phpmyadmin · /pma"},
{honeypot.FamilyTomcat, "/manager/html", "/manager/html · 401 Basic"},
{honeypot.FamilyJenkins, "/jenkins/login", "/jenkins"},
{honeypot.FamilyGrafana, "/grafana/login", "/grafana"},
{honeypot.FamilyGitLab, "/users/sign_in", "/users/sign_in"},
{honeypot.FamilyLuCI, "/cgi-bin/luci", "/cgi-bin/luci"},
{honeypot.FamilyJoomla, "/administrator/index.php", "/administrator"},
{honeypot.FamilyGeneric, "/admin", "/admin · /console"},
}
var cards strings.Builder
for _, it := range items {
name := it.fam.String()
body := honeypot.RenderFamily(it.fam, honeypot.LoginPageVars{
Action: it.action,
Redir: "/wp-admin/",
Failed: false,
})
if err := os.WriteFile(filepath.Join(dir, name+".html"), body, 0o644); err != nil {
panic(err)
}
fmt.Fprintf(&cards, `<figure><figcaption><b>%s</b><span>%s</span></figcaption><iframe src="%s.html" title="%s"></iframe></figure>`,
name, it.note, name, name)
}
page := `<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8">
<title>蜜罐伪装家族预览</title>
<style>
body{margin:0;padding:28px 24px 40px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#f6f7f9;color:#1d2327}
h1{font-size:18px;font-weight:600;margin:0 0 6px}
p.lead{margin:0 0 22px;font-size:13px;color:#646970}
.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(360px,1fr));gap:18px}
figure{margin:0;background:#fff;border:1px solid #dcdcde;border-radius:8px;overflow:hidden}
figcaption{display:flex;justify-content:space-between;gap:8px;padding:9px 12px;font-size:12px;border-bottom:1px solid #f0f0f1}
figcaption span{color:#787c82}
iframe{width:100%;height:520px;border:0;display:block}
</style></head><body>
<h1>蜜罐：9 个伪装家族</h1>
<p class="lead">每个 iframe 是 /wp-admin 这类诱饵路径的真实响应（同一份 RenderFamily 输出，未做任何美化）。Tomcat 家族在真实响应里是 401 + Basic Auth，这里有页面是为了看内容。</p>
<div class="grid">` + cards.String() + `</div></body></html>`
if err := os.WriteFile(filepath.Join(dir, "index.html"), []byte(page), 0o644); err != nil {
panic(err)
}
fmt.Println("预览已生成：", filepath.Join(dir, "index.html"))
}
dev/s3stub/s3_stub.go
+2 -12
View File
@@ -7,21 +7,13 @@
package storage
import (
"io"
"mime/multipart"
)
// MaxUploadBytes 与真实实现保持一致（8MB 单图上限，bodylimit 中间件依赖此值语义）。
const MaxUploadBytes = 8 * 1024 * 1024
// EncodeSpec 与真实实现的编码档位结构保持字段一致。
type EncodeSpec struct {
MaxSide int
Quality float32
}
// GeneralEncodeSpec 与真实实现保持一致（route/question 引用）。
var GeneralEncodeSpec = EncodeSpec{MaxSide: 1600, Quality: 80}
func UploadPictureToS3(file multipart.File, fileHeader *multipart.FileHeader) (string, error) {
return "", nil
}
@@ -34,8 +26,6 @@ func UploadBackgroundToS3(file multipart.File, fileHeader *multipart.FileHeader)
return "", nil
}
func ConvertStaticImageToWebP(data []byte, spec EncodeSpec) ([]byte, error) { return nil, nil }
func ConvertGifToAnimatedWebP(gifData []byte) ([]byte, error) { return nil, nil }
func ConvertStaticImageToWebP(r io.Reader) ([]byte, error) { return nil, nil }
func isSupportedImage(data []byte) bool { return true }
dev/sigv4ref/main.go
-51
View File
@@ -1,51 +0,0 @@
// 临时校验程序：用 aws-sdk-go-v2 的 SigV4 signer 给同一请求签名，
// 与 dev/theme-builder/serve.py 手写的实现比对。验证完即删。
//
// 每行 stdin：method \t url \t region \t payloadHash \t amzDate
package main
import (
"bufio"
"context"
"fmt"
"net/http"
"os"
"strings"
"time"
v4 "github.com/aws/aws-sdk-go-v2/aws/signer/v4"
"github.com/aws/aws-sdk-go-v2/credentials"
)
func main() {
keyID := os.Getenv("AWS_KEY_ID")
secret := os.Getenv("AWS_SECRET")
s := bufio.NewScanner(os.Stdin)
for s.Scan() {
line := strings.TrimSpace(s.Text())
if line == "" {
continue
}
f := strings.Split(line, "\t")
method, urlStr, region, payloadHash, ts := f[0], f[1], f[2], f[3], f[4]
t, err := time.Parse("20060102T150405Z", ts)
if err != nil {
panic(err)
}
req, err := http.NewRequest(method, urlStr, nil)
if err != nil {
panic(err)
}
req.Header.Set("X-Amz-Content-Sha256", payloadHash)
creds := credentials.NewStaticCredentialsProvider(keyID, secret, "")
c, err := creds.Retrieve(context.Background())
if err != nil {
panic(err)
}
if err := v4.NewSigner().SignHTTP(context.Background(), c, req, payloadHash, "s3", region, t); err != nil {
panic(err)
}
fmt.Println(req.Header.Get("Authorization"))
}
}
dev/sync-wsl.sh
-31
View File
@@ -1,31 +0,0 @@
#!/usr/bin/env bash
# 把 Windows 侧工作区同步到 WSL 里的测试部署目录。
#
# 为什么不能直接 rsync --delete：WSL 侧有几份「只存在于目标机」的文件，
# 源目录里没有它们，--delete 会把它们当多余文件删掉：
# - conf/app.ini 本地测试配置（数据库密码、对象存储密钥；模板见 dev/wsl-app.ini）
# 第一次踩这个坑时整份 app.ini 被删，服务器重启后起不来。
#
# 用法：在仓库根目录执行
# bash dev/sync-wsl.sh
set -euo pipefail
SRC="$(cd "$(dirname "$0")/.." && pwd)"
DST=/home/tamakyi/tb/src
cd "$SRC"
tar -cf - \
--exclude=.git \
--exclude=outputs \
--exclude=.workbuddy \
. 2>/dev/null |
wsl -d Debian -e bash -c '
set -e
DST=/home/tamakyi/tb/src
rm -rf /tmp/tbsync && mkdir -p /tmp/tbsync
tar -xf - -C /tmp/tbsync
# 只同步代码与资源，绝不动目标侧的 conf/app.ini
rsync -a --delete --exclude "conf/app.ini" /tmp/tbsync/ "$DST"/
rm -rf /tmp/tbsync
echo "SYNCED -> $DST"
'
dev/theme-builder/README.md
-403
View File
@@ -1,403 +0,0 @@
# 主题生成器
一个可视化编辑主题的小工具：**以项目真实页面为画布**，按页面分别摆装饰，导出 zip 解压即用。
它替换了早先那版「单文件、仿制预览」的生成器 —— 那一版的问题很直接：预览是我自己画的
示意图，跟真实页面长得不一样；而且只能配「背景 + 人物 + 道具」三件套。
## 为什么需要起一个本地服务
生成器要把 `outputs/preview-*.html`（由 `go test` 渲染出来的**真实页面**）放进 iframe 当画板，
再往里注入正在编辑的主题 CSS。`file://` 下浏览器不允许父页面访问 iframe 的 DOM（即使同目录），
预览就只能退回示意图。起本地服务后父子同源，拖拽、注入、实时改令牌都能工作。
```bash
# 1) 先渲染真实页面快照（改了模板/数据后要重跑）
TEST_PREVIEW=1 go test ./templates -run TestGenPreview
# 2) 起服务（只读，不改项目任何文件）
python dev/theme-builder/serve.py # 默认监听 0.0.0.0:8777，同局域网可访问
python dev/theme-builder/serve.py --host 127.0.0.1 # 只给本机用（公共网络请加这个）
# 3) 打开终端里打印的地址
# 本机 http://127.0.0.1:8777/dev/theme-builder/
# 局域网 http://192.168.x.x:8777/dev/theme-builder/
```
默认绑 `0.0.0.0`，是为了能躺在床上用手机 / 平板调主题：启动时会把本机各网卡的地址都列出来，
照着点就行（手机与电脑要在同一网段）。第一次启动 Windows 会弹防火墙询问，要允许私有网络。
⚠️ 两个必须知道的点：
- **上传接口没有账号体系**：能打开这个端口的人，都能用你填的密钥往对象存储写 / 删文件。
公共网络（咖啡馆、宿舍、公司网）一律 `--host 127.0.0.1`。写接口还会校验 `Origin` 与
`Host` 同源，挡掉「别的网页借你浏览器发请求」，但挡不住同网段主动连过来的人。
- **换地址 = 换 origin**：`127.0.0.1` 与 `192.168.x.x` 在浏览器眼里是两个站点，
草稿（localStorage）与 S3 密钥（sessionStorage）不共享 —— 第一次用新地址要重填一次密钥。
不想用脚本也行：在项目根跑 `python -m http.server 8777`，但那就只有静态预览、没有上传能力。
## 它和线上是同一条链路
| 环节 | 生成器 | 线上 |
| --- | --- | --- |
| 画板 | `outputs/preview-*.html`（真模板渲染） | 同一套模板 |
| 作用域 | iframe 里设 `data-page-scope` | `internal/context.pageScope()` 输出到 `<html>` |
| 装饰层 | **固定 10 槽** | `base.css` 的 12 层背景（pattern 1 + deco 10 + image 1） |
| 位置 | `calc(0%|50%|100% ± Npx)` | 同一套 `background-position` |
因为是同一套机制，工具里拖出来的位置换视口不会跑位，也不会出现「预览好看、实机错位」。
## 三块面板
**页面** —— 每个页面作用域可以单独配，各有一份背景与装饰：
| 作用域 | 对应路径 |
| --- | --- |
| 全局 | 所有页面默认 |
| `box` | `/_/{domain}` 箱主页 |
| `question` | `/_/{domain}/{id}` 单题页 |
| `admin` | `/user/questions` 题目列表 |
| `profile` | `/user/*` 设置页 |
| `vote` | `/vote/{token}` 投票页 |
默认全部「跟随全局」；勾掉就变成独立配置，导出时才会产出覆盖块。
没配的页面自动沿用全局，不会出现「某页装饰消失」。
以前「跟随全局」时背景下拉和「加一层」都是 disabled —— 用户在箱主页看到背景还在、
又点不动，这就是「背景图关不掉」的来源。现在：
- 「加一层」「改背景」永远可点，**一改就自动把这一页切成独立配置**，并把全局当前值复制过来当起点
（改背景不会顺带把图案和图层弄丢；图层重新发 id，避免两个作用域共用一批 id，拖拽/高亮会串）；
- 这种状态下图层列表不展示全局的层、也不给拖拽框 —— 否则一拖就改到全局去了；
- 想主动切换用「跟随全局」复选框，或用列表里的「改为独立配置」按钮。
（首页 `/` 与 `/explore` 不列出来 —— 全站公开页不注入 `ThemeSlug`，不加载主题 css，配了也没效果。）
**装饰图层** —— 每个作用域最多 10 层，三种类型：
- **图片**：从图片池选，选中后可直接在画板上拖动；
- **光斑**：`radial-gradient`，给空白一点体积，不占位、不会变成贴纸；
- **线性光**：`linear-gradient`，做窗光/压深。
锚点用 9 宫格 + 像素偏移，生成 `calc(0% + 40px) calc(100% - 36px)` 这种两值形式。
### 尺寸单位 × 视口（「换个屏幕就被裁」的根因）
装饰层是**视口固定层**（`background-attachment: fixed`），所以同一个 `400px` 在 900 高的屏幕上占
44%、在 768 的旧笔电上占 52%，窄屏上直接被切掉。尺寸单位就是回答「屏幕变小的时候这张图怎么办」：
| 单位 | 生成 | 适合 | 低于 100% 视口时的兜底 |
| --- | --- | --- | --- |
| `fit` 自适应·按高度 | `auto clamp(min(calc(100vh - 24px), 231px), 46.67vh, 420px)` | 人物立绘、竖幅道具 | 下限让位给视口，永远不纵向溢出 |
| `fitw` 自适应·按宽度 | `clamp(min(calc(100vw - 24px), 587px), 70.57vw, 1067px) auto` | 横幅、整屏插画 | 下限让位给视口，永远不横向溢出 |
| `px` 固定 | `auto 420px` | 需要绝对尺寸（如对齐某个 UI 元素） | 不缩，会裁 |
| `vh` 视口比例 | `auto 46.67vh` | 一定要占同样屏高的元素 | 无下限 |
**为什么必须有两种自适应**：`fit` 只按高度缩，宽度跟着比例涨 —— 一张 16:9 场景 `h=600` 在 1024 宽下
是 910px 刚好，在 390 的竖屏上按高度缩完还有 1001px，照样裁两侧。宽幅素材只能按宽度缩。
`fitw` 就是干这个的。实测同一张 1920×1080 素材：
| 视口 | `px 600` | `fit`（按高） | `fitw`（按宽） |
| --- | --- | --- | --- |
| 1512×900 | 1067 宽 | 1067 宽 | 1067 宽 |
| 1024×768 | 1067 宽 | 910 宽 | 723 宽 |
| 390×844 | 1067 宽（裁） | 1001 宽（裁） | 366 宽（完整） |
`min(calc(100vh - 24px), 231px)` 这一段是关键：`clamp()` 的下限如果固定成「基准的 55%」，
屏幕小到连 55% 都放不下时还是会溢出。让下限与视口取小值，自适应单位就不会把图撑出屏幕。
**每个图层底部有一行实测**：`1512×900 下显示 131×420，完整可见（源 300×960）`，
溢出时会变成橙色 `⚠ 1024×768：左 88px / 右 88px 越界`，并给一个「按 1024×768 修好」按钮
（改成固定 px 并算出刚好放下的尺寸）。视口栏可以切 1512/1280/1024/820/390 五档 —— 都是真视口高，
不是只改宽度，因为裁切几乎全由高度决定。
导出前还会再扫一遍，把「哪些层在哪些视口下越界」附在结果里（只提醒，不阻止 ——
故意让插画出血也是合法设计）。
**每一行都能直接换图**：行里带缩略图 + 「图片」下拉，一眼看到这层用的是哪张。
之前换图的下拉只出现在「选中那一层」的编辑器里，加上新层又默认绑第一张素材，
连加三层就全是同一张图，看起来像「每层只能显示这张、换不了」。
现在新加的层**不会**自动绑第一张（只有素材池只剩一张时才绑），行里显示「（选图片）」等你选。
**↑ / ↓ 调层级**。顺序就是层级：`background-image` 的第一层画在最上面，
所以「谁挡住谁」是靠顺序定的（shiroko 里自行车被人挡住就是这么来的）。
**窄屏** —— 手机上卡片几乎占满屏幕，桌面那套 16:9 场景会被 `cover` 裁成一条无意义纹理。
三段优先级从高到低：
1. **隐藏全部装饰层（急停）** —— 一键全关，最省事；
2. **每层的窄屏策略**：原样 / 缩小到 N%（缩放系数默认 62%）/ 隐藏。缩小是把高度与偏移
一起乘系数，锚点不变，所以「贴底靠左」的构图缩完还在原位；
3. **尺寸单位**：`fit` / `fitw` 的层浏览器会自己按视口缩，**不依赖这段规则**。
这一栏还能指定竖版背景图、改断点（默认 900px）。导出时生成 `@media` 块，只写浅色规则
（深色块特异性更高，本来就压住它）。
⚠️ `@media` 里**每个独立配置的页面都要各写一条** `html[data-theme-style][data-page-scope="x"]`：
页面覆盖块特异性是 (0,2,1)，只写 `html[data-theme-style]`（0,1,1）的话，
独立配置的页面在手机上根本不生效（旧版本就是这个 bug）。
⚠️ 竖版图只替换**本来就有背景图**的页面。某页故意配成纯色（`--tb-page-image: none`），
手机上新塞一张竖图等于改了他的设计。
**整页背景 · 焦点** —— 背景图是 `cover`，宽高比不匹配就必裁。九宫格焦点决定裁哪一边：
16:9 场景在竖屏上只剩中间一条，人物偏一侧时把焦点挪过去才不会裁到脸。
生成 `--tb-page-position`（`base.css` 里以 `var(--tb-page-position, center center)` 兜底，
旧主题不写这个令牌也不会坏）。
**配色** —— 只填 6 个基础色（底色 / 卡片 / 顶栏 / 正文 / 主色 / 边框），
其余 4 个派生：`surface-2` 往正文靠、`surface-hover` 往主色靠、`primary-weak` 加 12% 透明、
`text-secondary` / `text-muted` 往底色淡出。
⚠️ **派生文字色有对比度下限，不是固定比例**。正文往背景淡出时，二分找到「最淡但仍 ≥ 目标」的位置：
次要文字 5.5:1、弱化文字 4.5:1（WCAG AA 正文）。旧版按「混 55%」硬算，
在浅底上直接掉到 2.9:1 —— `base.css` 特意把 `--tb-text-muted` 从 `#8a919c` 提到 `#6b7280`（4.83:1），
生成器按固定比例算等于每导出一次就把那个修复覆盖回去。
- 卡片是半透明（`rgba(255,255,255,0.86)`）时先**压平到页面底色**再算，否则白卡会被当成纯白、对比度偏低；
- 同时检查页面底色与卡片两个背景，取更不利的那个；
- 手填的正文本身就达不到目标时**原样返回**（不再往淡里调）——宁可不够淡，不能产出看不见的字；
- 面板底部有读数 `正文 12.5:1 · 次要 5.5:1 · 淡文字 4.6:1 · 主色 4.6:1`，低于 4.5 变橙（手填色只提醒不拦）。
主色除了当链接色，还当按钮/标签的**背景**，所以还要交代「压在上面的字」：
导出时写 `--tb-on-primary`，在白字和深字（`#0b1016`）里挑对比度更高的那个。
浅色主题主色深 → 白字；深色主题主色普遍偏亮（`#5c8dff` 之流）→ 白字只有 2.2~3.1:1，必须换深字。
主色卡在**中间调**时两种字都不够 —— 面板会给橙色提示「压深一点配白字，或提亮一点配深字」，
`?dump=palette` 里也会列进 `warnings`（不判失败：那是主色要调，不是工具挑错）。
顺带：这套字号阶梯（`--tb-fs-xs…hero`）来自 `base.css`，生成器**不碰字号** ——
主题的职责是配色与背景，改字号会连带挤坏所有页面排版。
**顶栏** —— 三档，只管「配色 → 顶栏」那个基色怎么用：
| 档位 | 输出 | 适用 |
| --- | --- | --- |
| 实色 | `--tb-navbar: rgb(...)` | 页面没有装饰层穿过顶栏；最简单 |
| 半透明 | `--tb-navbar: rgba(...,0.72)` + `backdrop-filter: blur(12px)` | 装饰层从角落长出来、会经过顶栏时（推荐） |
| 全透明 | `--tb-navbar: transparent` | **只能预览**，导出会被拦 |
- 半透明档的两个滑杆：不透明度 0.2~0.95、背景模糊 0~24px。令牌只能是颜色值，
模糊另外写成 `.uk-navbar-container:not(.uk-navbar-transparent)` 规则（深浅两套共用一条）。
- 面板底部有 `导航文字 6.0:1` 的读数，按**压平后的顶栏**算（半透明时是「顶栏压在底色上」的结果，
不是顶栏色本身）。低于 4.5 变橙 —— 装饰层从顶栏后面穿过时还会更低，取最不利情况定透明度。
- ⚠️ **全透明不给导出**：顶栏一透明导航就失去依托、文字直接压在花纹上，比"被裁一段"更糟。
这一档留着的唯一用途是**预览对比**；`validate()` 会拦，仓库的 `TestNavbarNotFullyTransparent`
也会拦（两处同一条规矩，生成器里绕过也没用）。
- 旧工程（配色里直接塞 `rgba(...,0.52)`）打开时按 alpha 反推档位：1 → 实色、0 → 全透明、其余 → 半透明。
**图片池** —— 上传任意张，浏览器本地转 WebP。导出时只打包实际用到的图。
每张图左上角有 `fx` 按钮，进处理面板（处理过的会高亮）。
### 图片处理
| 功能 | 说明 |
| --- | --- |
| 不透明度 | 0~100%。CSS 背景图没法单独设 `opacity`，只能烘焙进像素 |
| 压白 / 雾度 | `v×(1-k)+255×k`。场景压白 38% 时人物常用 12~26%，否则是全页对比度最高的一块 |
| 去色 | 往灰度混。彩色素材压不住素场景时用 |
| 裁掉透明边 | 生成图四周留白多时裁掉，否则按高度定尺寸会让主体看着比实际小 |
| 去白底 | 四边漫水 + 封闭白孔检测，默认容差 16 |
| 边缘收 1px | 去白底后把残留的半透明白边收掉，代价是轮廓缩一圈 |
**非破坏**：原文件字节存在 `orig` 里，`fx` 只存参数，每次处理都从 `orig` 重算。
所以「压白 16% → 改成 20%」不会叠加两次压缩，反复调参也不会把边缘越磨越糊。
打开面板看一眼就关，一个像素都不会动（参数没变就跳过重编码）。
**去白底的两个关键点**（都是踩过的）：
- **封闭白孔**：手内侧、两腿之间那种被轮廓包住的白色，四边漫水根本进不去，
必须单独按连通域掏（面积 ≥ 24 才掏，更小的多半是眼睛高光）。可以关掉。
- **容差别贪**：背景常见 253，白袜子 237，只差 16。容差 16 保得住袜子，30 就吃穿了。
实测白底立绘去白底后透明占比 46.3%，与手写 floodfill 抠出来的 46.6% 差 0.3%。
## 导出画质
WebP 体积 ≈ 像素数 × 质量。**真正的大头是像素**：CSS 里只显示 400px 高的立绘，
2 倍屏也只要 800px，上传 3000px 的图纯属白扛。所以顺序是：先砍长边，再降质量。
| 设置 | 默认 | 说明 |
| --- | --- | --- |
| 质量 | 0.88 | 0.85~0.9 肉眼几乎看不出差别，低于 0.8 才明显糊 |
| 长边上限 | 1600 | 只缩不放。整页背景建议 1920/不限制；装饰人物 1200 够用 |
| 素材前缀 | 空 | 空 = 图片放 `static/images/themes/<slug>/` 随二进制发布；填 `https://cdn.example.com/themes` = CSS 写绝对地址，图片放自己的对象存储（R2 / MinIO / B2 / OSS / COS，任何 S3 兼容都行）。**前缀里不要带 slug** |
导出的 CSS 只有 `urlOf()` 一处决定图片地址，图层、背景、窄屏块全走它，不会出现
「背景走 CDN、装饰还指本地」的半吊子状态。素材前缀只影响导出，预览永远是内联 dataURL。
详细取舍（生成器前缀 / 应用内 301 / 边缘改写）见 `docs/theme-assets-cdn.md`。
## 素材托管（本地 / 任意 S3 兼容）
「图片放哪」由你自己定，面板里二选一：
- **本地**（默认）：打进 `static/images/themes/<slug>/`，随二进制发布。部署即生效、不依赖外部服务，
代价是换一张图要重新编译。
- **S3 兼容存储**：传到你自己的对象存储，导出的 CSS 写绝对地址。这里刻意不锁厂商 ——
R2 / MinIO / Backblaze B2 / 阿里 OSS(S3) / 腾讯 COS(S3) 用的是同一套 SigV4，
差别只在 `Endpoint`、`Region`、是否路径风格，全都做成了字段。
填好 Endpoint / Region / 桶名 / 路径前缀 / 密钥后：
1. **测试连接** —— 依次验四件事：`HEAD` 桶（连通与凭据）、`PUT` 一个探针对象（写权限）、
`GET` 读回比对（内容一致）、匿名 `GET`（传上去的图能不能被浏览器直接读到），最后删掉探针。
失败时会把 S3 的 `<Code>` 翻成人话（`SignatureDoesNotMatch` → 密钥/Region/时钟三选一）。
2. **上传素材** —— 把本次主题真正引用到的图（与导出同一个集合，`usedAssetIds()`）逐张 PUT，
键为 `<路径前缀>/<slug>/<id>.webp`，带 `Cache-Control: public, max-age=31536000, immutable`。
成功后自动把上面的「素材前缀」填成推导出的公开地址。
⚠️ 上传走的是本机 `serve.py` 的 `/api/s3/test`、`/api/s3/upload`，浏览器不直连对象存储 ——
所以**不用给桶配 CORS**，密钥也不会出现在页面发往第三方的请求里。它只存在当前标签页的
`sessionStorage` 与内存：不进 `localStorage` 草稿、不进工程 json、不进导出 zip。
用 `python -m http.server` 起的只有静态服务，探测不到接口时按钮会禁用并说明原因。
公开地址留空时按 endpoint 推导（path 风格 = `<endpoint>/<桶>/<前缀>`）。R2 与私有桶
需要自定义域或 CDN 域名，那种情况自己填「公开前缀」。测试里的「匿名可读」会给一条提醒，
但不会拦上传 —— 很多人就是靠自定义域分发的。
### 检测与清理
传上去只是第一步，「传上去之后对不对」是另一回事：同一个 slug 传过三次、换过 slug
旧图还留在桶里、重新导出后远端还是旧版 —— 这些在页面上都看不出来。所以还有一块
「远端素材」，点「**检测**」列出 `<路径前缀>/<slug>/` 下所有对象，按对象键名跟本地比：
| 状态 | 判断依据 | 能做什么 |
| --- | --- | --- |
| 一致 | 远端大小 == 本地编码后大小 | — |
| 旧图 | 同名但大小不同（多半重新导出过） | 行内 ↻ 用本地覆盖 |
| 多余 | 远端有、当前主题已不再引用（换过 slug / 删过素材） | 行内 ✕ 或「删除多余」批量删 |
| 缺失 | 本地有、远端没有 | 「补齐差异」一次传完 |
- 「**补齐差异**」只传缺失 + 旧图，一致的不重传（省流量也省时间）；
- 「**删除多余**」列清单后二次确认，走 `DeleteObject`（幂等，不存在的键也算成功）；
- 改过 slug 会提示「重新检测」—— 拿旧主题的清单去比新主题，会满屏「多余」；
- 只动远端，本地素材与工程文件不受影响。
厂商怎么填（2026 年的常见值，各家控制台都有「S3 API」页面）：
| 厂商 | Endpoint | Region | 路径风格 |
| --- | --- | --- | --- |
| Cloudflare R2 | `https://<账号ID>.r2.cloudflarestorage.com` | `auto` | 勾选 |
| MinIO（自建） | `http://<host>:9000` | `us-east-1`（看服务端配置） | 勾选 |
| Backblaze B2 | `https://s3.<区域>.backblazeb2.com` | 区域名，如 `us-west-004` | 勾选 |
| 阿里云 OSS | `https://s3.oss-<区域>.aliyuncs.com` | 区域，如 `cn-hangzhou` | 看控制台 |
| 腾讯云 COS | `https://cos.<区域>.myqcloud.com` | 区域，如 `ap-hangzhou` | 看控制台 |
AWS S3 或已绑定的桶级自定义域可以取消「路径风格」（走 `<桶>.<endpoint>`）。
两条自检（都在本目录，不依赖 UI）：
```bash
python dev/theme-builder/check_sigv4.py # 与 aws-sdk-go-v2 的 signer 逐字节对拍
python dev/theme-builder/selftest_upload.py # 起假 S3，跑「测试连接 → 上传 → 读回」
python dev/theme-builder/mock_s3.py --port 9900 # 想手动点面板时，先起这个假 S3
# 生成器在别的设备上打开时，假 S3 也要 --host 0.0.0.0，面板里的 Endpoint 填本机 IP
```
面板底部实时显示 `3 张，共 19KB；最大一张 bg.webp 7KB（1920×1080）`。
改完立刻按「原图 + fx 参数」重编码全部素材，并报出省了多少 —— 与图片处理同一条非破坏原则，
来回试不会叠加压缩。
⚠️ 两个反直觉的实测结论（都在 `?dump=quality` 里做了断言）：
- **`quality = 1` 不能用**。Skia 在这个值会切到 WebP 无损模式，输出反常：同一张噪声图
q=1 只有 52KB，q=0.95 是 440KB。滑块上限卡 0.95，`canvasAsset` 里也夹一道。
- **平涂/线稿降质量可能变大**。有损编码对纯色会引入噪点，噪声图 q 从 0.6 到 0.95 体积涨 75%，
而平涂图怎么调都是 1KB —— 不能承诺「降 q 一定更小」。这类素材优先调长边。
缩小走 `imageSmoothingQuality = 'high'`，一次缩太多也不会糊成一团。
## 工程文件与草稿
调主题是连续几十次的活，所以配置必须留得住：
- **新建**：顶栏按钮，清空当前工程并删掉浏览器草稿（有二次确认）。
之前只有 `?fresh=1` 这个隐藏参数 —— 用户看到「上次的数据」一直在，就会以为关不掉。
- **自动草稿**：每次改动后 700ms 存进 `localStorage`，下次打开自动恢复。
图片多到顶破 5MB 配额时会提示改用 json（只提示一次）。
- **保存工程 / 打开工程**：`theme-<slug>.json`，图片以 base64 内嵌，一个文件就能带走；
可以进版本库，也可以发给别人接着改。
- 不想恢复草稿就加 `?fresh=1`。
## 导出
点「导出 zip」得到：
```
static/css/themes/<slug>.css
static/images/themes/<slug>/*.webp
INSTALL-<slug>.txt
```
点导出时会先跑一遍校验（slug 合法、图片层是否选了图、有没有引用已删除的素材、
装饰是否超过 10 层、生成出来的 CSS 每处装饰是不是真的 10 个值），有问题直接列出来，
不会让你导出后再去等 `go test`。
导出结果会报「几个文件 / 总共多大 / 其中几张图共多大」，并附上「哪些层在哪些视口下越界」——
看到 `其中 4 张图共 3.2MB` 就该回去调长边上限了。
解压到项目根，然后按 `INSTALL-<slug>.txt` 做三步：
1. `conf/app.ini` 的 `[theme] available` 加上 slug；
2. `internal/conf/static.go` 的 `StaticVersion` +1；
3. `go build`（模板与静态资源都是编译期 embed，只重启不重编不会变）。
设置页下拉里显示的**就是 slug**。想要中文/日文名，到 `internal/i18n/dict_*.go` 加
`theme.name.<slug>` 词条（四份词典都要加）。不加也不会露 key —— 模板走 `themeName`
函数，缺词条时回退成 slug（见 `internal/theme.DisplayName`）。
⚠️ **窄屏段导出前先看一眼「窄屏隐藏全部装饰层」有没有勾着**：勾着的话 `@media` 会把
10 个槽位全写成 `none`，桌面完全正常、手机上一个素材都没有 —— 这是「素材在窄屏下消失」
最常见的来源。现在勾选时面板会给橙色警告、图层行标「窄屏隐藏」、加层和导出时也会再提醒一次。
## 它不做什么
- **不做复杂修图**：没有笔刷、蒙版、自由裁切、调色曲线 —— 这些该在专门的工具里做完再进来。
- **不做调色**：想统一「雾度」（人物压白 16%、场景 30~38%）得在生成端做，
见 `docs/theme-shiroko-assets-spec.md`。
- **不写配置**：`[theme] available` 只给要粘贴的那一行。
- **不碰深色的图片**：深色块一律 `--tb-page-image: none` + 装饰全关（白天场景压在深底上会脏）。
想在深色下也放图，需要手工加深色块。
## 自检
没有 UI 也能回归，两个钩子：
```
?demo=1 载入示例素材（canvas 画的背景 + 剪影人物）
?narrow=hide 直接落在「窄屏隐藏全部装饰层」状态（复现「素材在手机上不见了」）
?rows=2 加 2 层并依次绑到不同素材（截图多图层效果用）
?scope=admin 直接落在某个作用域
?fresh=1 忽略 localStorage 草稿，从空白开始
?dump=css 把最终 CSS 写进 <pre id="dump">
?dump=zip 把 zip 的 base64 写进 <pre id="dump">
?dump=validate 把 validate() 的结果写进 <pre id="dump">
?dump=install 把安装说明写进 <pre id="dump">
?dump=fx 跑处理算法自检（13 个断言，输出 JSON）
?dump=fxpipe 跑弹窗链路冒烟（打开→改参→预览→落盘→无改动不重编码）
?dump=layers 图层/作用域回归（加层默认不绑图、行内换图、自动切独立、新建清空）
?dump=fit 尺寸自适应回归（五档视口占用、溢出检测、fitw、旧工程兼容、@media 覆盖各作用域）
?dump=quality 画质回归（q 单调性、q=1 被夹到 0.95、长边上限真的压像素）
?dump=palette 派生文字色的对比度回归（四种配色下 ≥AA、层级不倒挂、手填低对比不继续变淡）
?dump=navbar 顶栏三档回归（实色无 blur、半透明带 alpha+blur、全透明被 validate 拦、alpha 边界）
?dump=fxkey 端到端去白底：载入白底图，统计透明像素比例
?loadurl=/static/images/x.webp&fx=x
直接把项目里的图当素材载入（不必先下载再上传），fx= 打开处理面板
?fxjson={"key":{"on":true}}
配合 loadurl 给初始处理参数
```
```bash
chrome --headless=old --virtual-time-budget=6000 \
--dump-dom "http://127.0.0.1:8777/dev/theme-builder/?demo=1&dump=css"
```
把抓到的 CSS 存成 `static/css/themes/<slug>.css`，可跑：
```bash
go test ./internal/theme -run "TestThemeCSSComplete|TestDecoSlotCount"
```
`TestDecoSlotCount` 是这次新增的：它会逐个检查 `base.css` 与所有主题 css 里每一处
`--tb-deco*` 声明是否都有 10 个值。少写一个不会报错，只会让图层与 size/position 错位
（表现为整页重复同一张插画，或人物跑到左上角），靠注释守不住。
dev/theme-builder/check_sigv4.py
-103
View File
@@ -1,103 +0,0 @@
"""校验 serve.py 手写的 SigV4 与 aws-sdk-go-v2 的 signer 逐字节一致。
为什么需要这个：SigV4 错一个字节，服务端只会回一句 SignatureDoesNotMatch，
既不说哪里错、也不会在本地暴露出来 —— 上传功能就成了「点了没反应」。
这里用官方 SDK 当参照实现做对拍，改完签名相关代码跑一遍即可。
用法（项目根）：
python dev/theme-builder/check_sigv4.py
⚠️ 用例只放 ASCII 键：aws-sdk-go-v2 裸 SignHTTP 默认会二次转义 URI，
而 S3 客户端内部把 DisableURIPathEscaping 设成了 true（单次编码）。
即同一个路径两种行为，把非 ASCII 键放进来只会比出「SDK 的两个模式之差」。
我们跟随 S3 客户端的单次编码（AWS 文档的 RFC3986 规则），并由生成器把
slug 限制在 [a-z0-9-_]，从根上避开这个争议区。
"""
import os
import subprocess
import sys
import urllib.parse
HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(os.path.dirname(HERE))
sys.path.insert(0, HERE)
import serve # noqa: E402
KEY_ID = "AKIAIOSFODNN7EXAMPLE"
SECRET = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
TS = "20130524T000000Z"
EMPTY = serve.EMPTY_SHA256
BODY_HASH = serve._sha256(b"TamaBox theme builder probe\n")
# (说明, method, endpoint, extra cfg, key, query)
CASES = [
("path-style 桶级 HEAD", "HEAD", "http://127.0.0.1:9000", dict(bucket="tb-assets"), "", None),
("path-style 带前缀对象", "PUT", "http://127.0.0.1:9000",
dict(bucket="tb-assets", prefix="themes"), "shiroko/bg1.webp", None),
("virtual-host 对象", "GET", "https://s3.us-west-004.backblazeb2.com",
dict(bucket="my-bucket", region="us-west-004", pathStyle=False), "themes/shiroko/bg1.webp", None),
("R2 region=auto", "PUT", "https://acc.r2.cloudflarestorage.com",
dict(bucket="cdn", region="auto", prefix="themes"), "x/a.webp", None),
("R2 虚拟主机", "GET", "https://acc.r2.cloudflarestorage.com",
dict(bucket="cdn", region="auto", pathStyle=False), "themes/s/t.webp", None),
("带端口 https", "DELETE", "https://minio.lan:9443",
dict(bucket="static", region="us-east-1"), "themes/s/t.webp", None),
# 带 query：ListObjectsV2 的 canonical query 要按键排序、逐项编码（/ 编成 %2F）
("ListObjectsV2 三参数", "GET", "http://127.0.0.1:9000", dict(bucket="tb-assets"),
"", {"list-type": "2", "max-keys": "1000", "prefix": "themes/shiroko/"}),
("ListObjectsV2 分页（乱序传入）", "GET", "https://acc.r2.cloudflarestorage.com",
dict(bucket="cdn", region="auto", pathStyle=False), "",
{"prefix": "themes/", "continuation-token": "1/abc+d", "max-keys": "2", "list-type": "2"}),
]
def build(endpoint, extra, key):
cfg = serve.S3Config(dict(extra, endpoint=endpoint, accessKey=KEY_ID, secretKey=SECRET))
if key:
path = cfg.object_path(key)
else:
path = ("/" + cfg.bucket) if cfg.path_style else "/"
return cfg, path
def go_sign(payloads):
env = dict(os.environ, AWS_KEY_ID=KEY_ID, AWS_SECRET=SECRET,
GOPROXY="https://goproxy.cn,direct", GOSUMDB="off", GOFLAGS="-mod=mod")
p = subprocess.run(["go", "run", "./dev/sigv4ref"], input="\n".join(payloads),
capture_output=True, text=True, env=env, cwd=ROOT)
if p.returncode != 0:
sys.stderr.write(p.stderr[-2000:])
raise SystemExit("go run 失败（检查 GOPROXY / Go 是否可用）")
return [x for x in p.stdout.strip().splitlines() if x.strip()]
def main():
payloads = []
for _, method, endpoint, extra, key, query in CASES:
cfg, path = build(endpoint, extra, key)
body = BODY_HASH if method == "PUT" else EMPTY
url = cfg.url(path) + (("?" + serve.canonical_query(query)) if query else "")
payloads.append("\t".join([method, url, cfg.region, body, TS]))
go = go_sign(payloads)
if len(go) != len(CASES):
raise SystemExit("返回条数不对：go=%d cases=%d" % (len(go), len(CASES)))
bad = 0
for (desc, method, endpoint, extra, key, query), g in zip(CASES, go):
cfg, path = build(endpoint, extra, key)
body = BODY_HASH if method == "PUT" else EMPTY
py = serve.sign_v4(cfg, method, path, body, TS, cfg.host, serve.canonical_query(query))
if g.rsplit("Signature=", 1)[-1] == py.rsplit("Signature=", 1)[-1]:
print("OK %s" % desc)
else:
bad += 1
print("DIFF %s\n go %s\n py %s\n path %s" % (desc, g, py, path))
print("\n%d/%d 一致" % (len(CASES) - bad, len(CASES)))
return 1 if bad else 0
if __name__ == "__main__":
raise SystemExit(main())
dev/theme-builder/index.html
-4001
View File
File diff suppressed because it is too large Load Diff
dev/theme-builder/mock_s3.py
-184
View File
@@ -1,184 +0,0 @@
"""最小 S3 兼容假服务，只为调试生成器的「测试连接 / 上传素材」。
它不校验签名（签名正确性由 check_sigv4.py 与官方 SDK 对拍保证），只校验
请求形态与权限分支，所以能用来演练：桶名写错、密钥写错、前缀为空、
虚拟主机风格这些配置。
独立跑：python dev/theme-builder/mock_s3.py --port 9900
被复用：from mock_s3 import MockS3, BUCKET
"""
import argparse
import sys
import threading
import urllib.parse
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
BUCKET = "tb-assets"
class MockS3(BaseHTTPRequestHandler):
store = {}
requests = []
def log_message(self, fmt, *args):
pass
# ---- helpers ----
def _split(self):
path = urllib.parse.unquote(self.path.split("?")[0]).lstrip("/")
bucket, _, key = path.partition("/")
return bucket, key
def _key_id(self):
# Authorization 形如
# AWS4-HMAC-SHA256 Credential=AKID/20261021/us-east-1/s3/aws4_request, SignedHeaders=...
# 第一个逗号前既有算法名又有 Credential，不能按逗号切完再比前缀。
auth = self.headers.get("Authorization") or ""
i = auth.find("Credential=")
if i < 0:
return ""
return auth[i + len("Credential="):].split("/")[0]
def _body(self):
n = int(self.headers.get("Content-Length") or 0)
return self.rfile.read(n) if n else b""
def _xml(self, status, code, message):
body = ("<?xml version=\"1.0\"?><Error><Code>%s</Code><Message>%s</Message></Error>"
% (code, message)).encode()
self.send_response(status)
self.send_header("Content-Type", "application/xml")
if self.command != "HEAD":
# HEAD 不能有 body：真 S3 也只是返回状态行，客户端仍会按状态码报错。
self.send_header("Content-Length", str(len(body)))
self.end_headers()
if self.command != "HEAD":
self.wfile.write(body)
def _check(self, bucket):
MockS3.requests.append((self.command, self.path, dict(self.headers)))
if self._key_id() == "BADKEY":
self._xml(403, "SignatureDoesNotMatch",
"The request signature we calculated does not match")
return False
if bucket != BUCKET:
self._xml(404, "NoSuchBucket", "The specified bucket does not exist")
return False
if not (self.headers.get("x-amz-date") or "").endswith("Z"):
self._xml(403, "AccessDenied", "missing x-amz-date")
return False
return True
# ---- verbs ----
def do_HEAD(self):
bucket, _ = self._split()
if not self._check(bucket):
return
self.send_response(200)
self.send_header("Content-Length", "0")
self.end_headers()
def do_PUT(self):
bucket, key = self._split()
data = self._body()
if not self._check(bucket):
return
MockS3.store[key] = (data, self.headers.get("Content-Type"),
self.headers.get("Cache-Control"))
self.send_response(200)
self.send_header("ETag", '"mock"')
self.send_header("Content-Length", "0")
self.end_headers()
def do_GET(self):
parsed = urllib.parse.urlsplit(self.path)
qs = urllib.parse.parse_qs(parsed.query)
bucket, key = self._split()
if not key and qs.get("list-type") == ["2"]:
if not self._check(bucket):
return
return self._list(qs.get("prefix", [""])[0],
int(qs.get("max-keys", ["1000"])[0] or 1000),
int(qs.get("continuation-token", ["0"])[0] or 0))
MockS3.requests.append((self.command, self.path, dict(self.headers)))
if key not in MockS3.store:
self._xml(404, "NoSuchKey", "The specified key does not exist")
return
data, ctype, _ = MockS3.store[key]
self.send_response(200)
self.send_header("Content-Type", ctype or "application/octet-stream")
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def _list(self, prefix, max_keys, offset):
# 只实现 ListObjectsV2 里服务端用到的字段；分页用 offset 当 token，够测真实分页逻辑。
keys = sorted(k for k in MockS3.store if k.startswith(prefix))
page = keys[offset:offset + max_keys]
truncated = offset + len(page) < len(keys)
items = []
for k in page:
data = MockS3.store[k][0]
items.append(
"<Contents><Key>%s</Key><Size>%d</Size>"
"<LastModified>2026-10-21T00:00:00.000Z</LastModified><ETag>&quot;mock&quot;</ETag></Contents>"
% (k, len(data)))
token = ("<NextContinuationToken>%d</NextContinuationToken>" % (offset + len(page))) if truncated else ""
body = (
'<?xml version="1.0" encoding="UTF-8"?>'
'<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">'
"<Name>%s</Name><Prefix>%s</Prefix><KeyCount>%d</KeyCount>"
"<MaxKeys>%d</MaxKeys><IsTruncated>%s</IsTruncated>%s%s"
"</ListBucketResult>"
% (BUCKET, prefix, len(page), max_keys, "true" if truncated else "false",
token, "".join(items))
).encode()
self.send_response(200)
self.send_header("Content-Type", "application/xml")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def do_DELETE(self):
bucket, key = self._split()
if not self._check(bucket):
return
MockS3.store.pop(key, None)
self.send_response(204)
self.send_header("Content-Length", "0")
self.end_headers()
def spin(port=0, host="127.0.0.1"):
"""起在后台线程，返回 (server, endpoint)。port=0 让系统挑空闲端口。
host 默认只给本机用；如果生成器是在别的设备上打开的（局域网访问），
要把这里改成 0.0.0.0，并在面板里把 Endpoint 填成本机 IP。
"""
srv = ThreadingHTTPServer((host, port), MockS3)
threading.Thread(target=srv.serve_forever, daemon=True).start()
shown = "127.0.0.1" if host in ("0.0.0.0", "::") else host
return srv, "http://%s:%d" % (shown, srv.server_address[1])
def main():
ap = argparse.ArgumentParser(description="TamaBox 主题生成器用的假 S3")
ap.add_argument("--port", type=int, default=9900)
ap.add_argument("--host", default="127.0.0.1",
help="监听地址，默认 127.0.0.1；生成器在别的设备上打开时用 0.0.0.0")
args = ap.parse_args()
srv, endpoint = spin(args.port, args.host)
print("假 S3 已启动：%s" % endpoint)
print(" 桶名 %s，Access Key 随意（写 BADKEY 会返回 SignatureDoesNotMatch）" % BUCKET)
if args.host in ("0.0.0.0", "::"):
print(" 局域网设备访问时，面板里的 Endpoint 填 http://<本机IP>:%d" % args.port)
print("Ctrl+C 停止")
try:
threading.Event().wait()
except KeyboardInterrupt:
srv.shutdown()
print("\n已停止")
if __name__ == "__main__":
sys.exit(main())
dev/theme-builder/selftest_upload.py
-152
View File
@@ -1,152 +0,0 @@
"""上传链路自测：起一个假 S3，跑一遍「测试连接 → 上传 → 读回」。
覆盖 serve.py 里真正容易错、又不能靠对拍发现的部分：
· 桶级 HEAD 与对象级 PUT/GET/DELETE 的路径拼接（path style / 虚拟主机）
· 前缀拼接、Content-Type、immutable 缓存头
· 4xx 时能否把 S3 的 <Code>/<Message> 还原成人话（含 hint）
签名数学由 check_sigv4.py 与官方 SDK 对拍保证，这里不重复。
用法（项目根）：
python dev/theme-builder/selftest_upload.py
"""
import base64
import os
import sys
HERE = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, HERE)
import serve # noqa: E402
from mock_s3 import BUCKET, MockS3 # noqa: E402
def spin():
import mock_s3
return mock_s3.spin()
FAILS = []
def check(desc, cond, extra=""):
print(("OK " if cond else "FAIL ") + desc + ((" ← " + extra) if extra and not cond else ""))
if not cond:
FAILS.append(desc)
def main():
srv, endpoint = spin()
base = dict(endpoint=endpoint, bucket=BUCKET, prefix="themes", region="us-east-1",
accessKey="AKID", secretKey="SECRET")
# 1) 测试连接：4 步应全过，探针最后被删掉
cfg = serve.S3Config(dict(base))
res = serve.test_connection(cfg)
check("测试连接返回 ok", res.get("ok") is True)
check("测试连接 4 步全过", all(s["ok"] for s in res["steps"]), str(res))
check("探针已清理", not any(k.startswith("themes/.tb-probe") for k in MockS3.store),
str(list(MockS3.store)))
# 2) 上传：前缀 / 内容 / 头都要对
f1 = b"\x52\x49\x46\x46fakewebp1"
f2 = b"\x52\x49\x46\x46fakewebp2"
up = serve.upload_files(cfg, [
{"key": "shiroko/asset1.webp", "contentType": "image/webp",
"data": base64.b64encode(f1).decode()},
{"key": "shiroko/asset2.webp", "contentType": "image/webp",
"data": base64.b64encode(f2).decode()},
])
check("上传全部成功", up["ok"] and up["total"] == 2 and up["failed"] == 0, str(up))
check("前缀拼进对象键", "themes/shiroko/asset1.webp" in MockS3.store, str(list(MockS3.store)))
stored, ctype, cache = MockS3.store.get("themes/shiroko/asset1.webp", (b"", None, None))
check("内容一致", stored == f1)
check("Content-Type = image/webp", ctype == "image/webp", str(ctype))
check("Cache-Control = immutable", "immutable" in (cache or ""), str(cache))
# 2b) 逐文件覆盖缓存头：README/清单这类「键不变、内容会变」的文件不能 immutable
serve.upload_files(cfg, [
{"key": "shiroko/INSTALL.txt", "contentType": "text/plain; charset=utf-8",
"cacheControl": "public, max-age=60",
"data": base64.b64encode(b"readme").decode()},
])
_, _, cc = MockS3.store.get("themes/shiroko/INSTALL.txt", (b"", None, None))
check("可覆盖 Cache-Control", cc == "public, max-age=60", str(cc))
# 这一步只为验头，别让它污染后面的对象计数
MockS3.store.pop("themes/shiroko/INSTALL.txt", None)
# 3) 错误密钥：HEAD 拿不到响应体（规范如此），只能按状态码归因；
# 真正能读到 S3 错误码的是带 body 的 PUT，所以用上传路径验证还原能力。
bad = serve.S3Config(dict(base, accessKey="BADKEY"))
try:
serve.test_connection(bad)
check("错误密钥应抛错", False)
except serve.S3Error as e:
check("HEAD 失败按状态码归因", e.status == 403 and e.code == "AccessDenied",
"%s %s" % (e.status, e.code))
badUp = serve.upload_files(bad, [{"key": "shiroko/x.webp", "contentType": "image/webp",
"data": base64.b64encode(b"x").decode()}])
codes = [f.get("code") for f in badUp["files"]]
check("PUT 失败能还原 SignatureDoesNotMatch", codes == ["SignatureDoesNotMatch"], str(codes))
check("该错误有中文提示", "签名不匹配" in serve.S3_HINTS.get("SignatureDoesNotMatch", ""))
# 4) 桶名写错：NoSuchBucket
wrong = serve.S3Config(dict(base, bucket="nope"))
try:
serve.test_connection(wrong)
check("错桶应抛错", False)
except serve.S3Error as e:
check("错桶 → NoSuchBucket", e.code == "NoSuchBucket", e.code)
# 5) 键里出现 .. 必须被拒（防止越权写到别的前缀）
try:
serve.full_key(cfg, "../etc/passwd")
check(".. 应被拒", False)
except ValueError:
check(".. 被拒绝", True)
# 6) 前缀留空 = 传桶根
plain = serve.S3Config(dict(base, prefix=""))
up2 = serve.upload_files(plain, [{"key": "root.webp", "contentType": "image/webp",
"data": base64.b64encode(b"x").decode()}])
check("空前缀传桶根", up2["ok"] and "root.webp" in MockS3.store, str(list(MockS3.store)))
# 7) 列远端：前缀过滤、大小、分页
serve.upload_files(cfg, [{"key": "shiroko/asset3.webp", "contentType": "image/webp",
"data": base64.b64encode(b"three").decode()}])
ls = serve.list_objects(cfg, "shiroko/")
keys = sorted(o["key"] for o in ls["objects"])
check("按 <前缀>/<slug>/ 列出 3 个对象",
keys == ["themes/shiroko/asset1.webp", "themes/shiroko/asset2.webp",
"themes/shiroko/asset3.webp"], str(keys))
size1 = [o["size"] for o in ls["objects"] if o["key"].endswith("asset1.webp")]
check("对象大小与上传字节一致", size1 == [len(f1)], str(size1))
paged = serve.list_objects(cfg, "shiroko/", max_keys=2)
check("分页把 3 个都取回来了", len(paged["objects"]) == 3, str(len(paged["objects"])))
everything = serve.list_objects(cfg, "")
# 空前缀 = 列「路径前缀」之下（跨主题），不扫整个桶：桶里还可能有头像等别的东西。
check("空前缀列出 <路径前缀>/ 下全部、且不越界",
all(o["key"].startswith("themes/") for o in everything["objects"])
and len(everything["objects"]) == 3,
str([o["key"] for o in everything["objects"]]))
# 8) 删除：幂等（不存在的键也当成功），且不影响别的前缀
del_res = serve.delete_objects(cfg, ["shiroko/asset3.webp", "shiroko/nonexistent.webp"])
check("删除含不存在的键仍算成功", del_res["ok"] and del_res["total"] == 2, str(del_res))
after = serve.list_objects(cfg, "shiroko/")
check("删完只剩 2 个", len(after["objects"]) == 2,
str([o["key"] for o in after["objects"]]))
check("桶根对象没被误删", "root.webp" in MockS3.store)
# 9) 虚拟主机风格的路径（不带桶名）
vh = serve.S3Config(dict(base, pathStyle=False))
check("虚拟主机路径不含桶名", vh.object_path("themes/a.webp") == "/themes/a.webp", vh.object_path("x"))
check("虚拟主机 host 带桶名", vh.host.startswith(BUCKET + "."), vh.host)
srv.shutdown()
print("\n%d 项失败" % len(FAILS))
return 1 if FAILS else 0
if __name__ == "__main__":
raise SystemExit(main())
dev/theme-builder/serve.py
-590
View File
@@ -1,590 +0,0 @@
#!/usr/bin/env python3
"""主题生成器的本地预览服务 + 素材上传代理。
为什么必须起服务：生成器不再自己画一个"仿制页面"，而是把项目真实渲染出来的
页面（outputs/preview-*.html）放进 iframe 当画板，再往里注入正在编辑的主题 CSS。
file:// 下浏览器不允许父页面访问 iframe 的 DOM（即使同目录），预览就只能退回示意图。
起一个本地 HTTP 服务后父子同源，拖拽、注入、实时改令牌都能正常工作。
为什么上传也走这个服务：浏览器直连对象存储要配 CORS、还要把密钥交给页面里的
fetch，各家 S3 兼容实现的 CORS 配置界面又都不一样。放到本机 Python 里代发，
生成器只跟 127.0.0.1 说话：不碰 CORS，密钥不落盘、不进工程文件、不进导出 zip。
用法（在项目根目录执行）：
python dev/theme-builder/serve.py # 默认 0.0.0.0:8777，同局域网可访问
python dev/theme-builder/serve.py --host 127.0.0.1 # 只给本机（公共网络用这个）
python -m http.server 8777 # 只有静态预览，没有上传能力
启动时终端会列出本机与各网卡的地址，照着打开即可。
这个脚本只读文件，不写任何东西，也不改项目配置。
"""
import argparse
import base64
import datetime
import functools
import hashlib
import hmac
import http.server
import json
import os
import re
import socket
import socketserver
import sys
import urllib.error
import urllib.parse
import urllib.request
# dev/theme-builder/serve.py → 上两级就是项目根
PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
# 单次请求体上限：一次上传十几张 1600px 的 WebP，base64 后约 1.4 倍体积，
# 64MB 足够，同时挡住误连到公网时的内存放大。
MAX_BODY_BYTES = 64 * 1024 * 1024
EMPTY_SHA256 = hashlib.sha256(b"").hexdigest()
# ---------------------------------------------------------------------------
# SigV4 签名
# ---------------------------------------------------------------------------
# 不用 boto3：这个脚本的定位是「零依赖、拷走就能跑」，装一个 SDK 只为签四个请求
# 不划算。下面是 AWS 文档里 SigV4 for S3 的最小实现，覆盖 PUT / GET / DELETE / HEAD。
def _hmac(key: bytes, msg: str) -> bytes:
return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
def _sha256(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def _quote_key(key: str) -> str:
"""按 AWS 规则编码对象键：保留 `/`，其余非 unreserved 字符全部百分号编码。
用 quote(safe='/-_.~') 而不是逐段 quote：两者等价，但后者容易漏掉空段
（`a//b`）导致的路径塌缩。S3 的签名 URI 必须与请求行完全一致，差一个字符
就是 SignatureDoesNotMatch。
"""
return urllib.parse.quote(key, safe="/-_.~")
def _quote_query(s):
"""query 的编码规则比 path 更严：`/` 也要编码成 %2F，只有 A-Za-z0-9-_.~ 原样保留。"""
return urllib.parse.quote(str(s), safe="-_.~")
def canonical_query(params):
"""按 AWS 规则拼 canonical query：先按键排序，同名多值再按值排序，逐项编码。
ListObjectsV2 的 `list-type` / `prefix` / `continuation-token` 全走这里。
顺序错、或漏了编码都是 SignatureDoesNotMatch —— 而 S3 不会告诉你差在哪。
"""
pairs = []
for k, v in (params or {}).items():
for one in (v if isinstance(v, (list, tuple)) else [v]):
pairs.append((_quote_query(k), _quote_query(one)))
pairs.sort()
return "&".join("%s=%s" % kv for kv in pairs)
def sign_v4(cfg, method, canonical_path, payload_hash, amz_date, host, query=""):
region = cfg.region
date = amz_date[:8]
signed_headers = "host;x-amz-content-sha256;x-amz-date"
canonical_headers = (
"host:" + host + "\n"
"x-amz-content-sha256:" + payload_hash + "\n"
"x-amz-date:" + amz_date + "\n"
)
# CanonicalHeaders 自身每行以 \n 结尾，与 SignedHeaders 之间因此有一个空行，
# 这是规范要求的形态，不是笔误。
canonical_request = "\n".join([
method, canonical_path, query or "", canonical_headers, signed_headers, payload_hash,
])
scope = date + "/" + region + "/s3/aws4_request"
string_to_sign = "\n".join([
"AWS4-HMAC-SHA256", amz_date, scope, _sha256(canonical_request.encode("utf-8")),
])
k = _hmac(("AWS4" + cfg.secret_key).encode("utf-8"), date)
k = _hmac(k, region)
k = _hmac(k, "s3")
k = _hmac(k, "aws4_request")
signature = hmac.new(k, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
return (
"AWS4-HMAC-SHA256 Credential=" + cfg.access_key + "/" + scope
+ ", SignedHeaders=" + signed_headers + ", Signature=" + signature
)
class S3Error(Exception):
def __init__(self, step, status, code, message):
Exception.__init__(self, message or code or ("HTTP %s" % status))
self.step = step
self.status = status
self.code = code
self.message = message or ""
# 常见错误 → 人话。签名失败是最常见的，原因几乎总是密钥/region/时钟三者之一。
S3_HINTS = {
"SignatureDoesNotMatch": "签名不匹配：核对 Secret Key 是否复制完整、Region 是否与桶一致（R2 填 auto），以及本机时间偏差是否超过 15 分钟。",
"InvalidAccessKeyId": "Access Key 无效：核对 ID，或该密钥没有这个桶的权限。",
"AccessDenied": "权限不足：这个密钥没有写权限，或桶策略禁止了该操作。",
"NoSuchBucket": "桶不存在：核对桶名与 Endpoint 是否属于同一账号/区域。",
"PermanentRedirect": "Endpoint 与桶所在区域不匹配：换对该区域的 Endpoint（或改用虚拟主机风格）。",
"AuthorizationHeaderMalformed": "Region 写错了：填桶实际所在区域（R2 用 auto，MinIO 常为 us-east-1）。",
"InvalidBucketName": "桶名不合法：S3 桶名只允许小写字母、数字、点和中划线。",
"RequestTimeTooSkewed": "本机时间与服务器偏差过大：校准系统时间后重试。",
}
def _parse_s3_error(body):
text = body[:2000].decode("utf-8", "replace")
code = re.search(r"<Code>([^<]+)</Code>", text)
msg = re.search(r"<Message>([^<]+)</Message>", text)
return (code.group(1).strip() if code else ""), (msg.group(1).strip() if msg else text.strip()[:200])
class S3Config:
"""一次上传用到的全部参数。只活在内存里，不落盘。"""
def __init__(self, d):
ep = str(d.get("endpoint") or "").strip()
if not ep:
raise ValueError("Endpoint 没填")
if "://" not in ep:
ep = "https://" + ep
u = urllib.parse.urlsplit(ep)
if u.scheme not in ("http", "https"):
raise ValueError("Endpoint 只支持 http / https")
if not u.hostname:
raise ValueError("Endpoint 里没有主机名")
# 路径部分一律忽略：Endpoint 只表达「服务在哪」，桶和键由字段决定。
self.scheme = u.scheme
self.port = u.port
self.host_only = u.hostname
self.region = str(d.get("region") or "").strip() or "us-east-1"
self.bucket = str(d.get("bucket") or "").strip()
if not self.bucket:
raise ValueError("桶名没填")
self.prefix = str(d.get("prefix") or "").strip().strip("/")
self.access_key = str(d.get("accessKey") or "").strip()
self.secret_key = str(d.get("secretKey") or "").strip()
if not self.access_key or not self.secret_key:
raise ValueError("Access Key / Secret Key 没填")
self.path_style = bool(d.get("pathStyle", True))
@property
def host(self):
if self.path_style:
return self.host_only if not self.port else "%s:%d" % (self.host_only, self.port)
return "%s.%s" % (self.bucket, self.host_only) + (":%d" % self.port if self.port else "")
def object_path(self, key):
"""S3 的签名 URI 必须与请求行逐字一致，所以两者共用这一个函数。"""
path = ("/" + self.bucket + "/" + key) if self.path_style else ("/" + key)
return _quote_key(path)
def url(self, path):
return "%s://%s%s" % (self.scheme, self.host, path)
def _now():
return datetime.datetime.now(datetime.timezone.utc)
def s3_request(cfg, method, key="", body=b"", content_type=None, cache_control=None,
query=None, timeout=25):
"""发一个签名请求。key 为空表示桶级操作（HEAD bucket / ListObjectsV2）。
返回 (status, headers, body)；4xx/5xx 不抛异常，交由调用方判断 —— 测试连接
需要把「403 是权限问题」和「连不上是网络问题」区分开讲。
"""
if key:
path = cfg.object_path(key)
else:
path = ("/" + cfg.bucket) if cfg.path_style else "/"
qs = canonical_query(query)
payload_hash = _sha256(body) if body else EMPTY_SHA256
amz_date = _now().strftime("%Y%m%dT%H%M%SZ")
auth = sign_v4(cfg, method, path, payload_hash, amz_date, cfg.host, qs)
url = cfg.url(path) + (("?" + qs) if qs else "")
req = urllib.request.Request(url, data=body if body else None, method=method)
req.add_header("x-amz-content-sha256", payload_hash)
req.add_header("x-amz-date", amz_date)
req.add_header("Authorization", auth)
if content_type:
req.add_header("Content-Type", content_type)
if cache_control:
req.add_header("Cache-Control", cache_control)
try:
with urllib.request.urlopen(req, timeout=timeout) as r:
return r.status, dict(r.headers), r.read()
except urllib.error.HTTPError as e:
return e.code, dict(e.headers), e.read()
except Exception as e: # URLError / timeout / SSL 错误
raise S3Error("connect", 0, "NetworkError", "%s（%s）" % (e, cfg.host))
def full_key(cfg, key):
key = str(key or "").strip().lstrip("/")
if not key:
raise ValueError("对象键为空")
if ".." in key.split("/") or "\\" in key:
raise ValueError("对象键不能包含 .. 或反斜杠：%s" % key)
return (cfg.prefix + "/" + key) if cfg.prefix else key
def probe_key(cfg):
stamp = _now().strftime("%Y%m%dT%H%M%S")
return full_key(cfg, ".tb-probe-%s.txt" % stamp)
def _public_read(url, timeout=10):
"""匿名 GET 一次，判断「传上去的图能不能直接被浏览器读到」。
这一步不是必须的（很多人会用自定义域/CDN），但它能把最常见的坑当场暴露：
桶是私有的，上传全成功、页面里全是 403。
"""
try:
with urllib.request.urlopen(url, timeout=timeout) as r:
return r.status == 200
except urllib.error.HTTPError as e:
return e.code == 200
except Exception:
return False
def test_connection(cfg):
steps = []
status, _, body = s3_request(cfg, "HEAD")
if status >= 400:
code, msg = _parse_s3_error(body)
if not code:
# HEAD 响应按规范没有 body，S3 的错误码拿不到。只能按状态码归因，
# 否则前端只能显示一句「HTTP 403」，用户完全不知道该改哪。
code = {403: "AccessDenied", 404: "NoSuchBucket",
301: "PermanentRedirect", 307: "PermanentRedirect",
400: "BadRequest"}.get(status, "HTTP%d" % status)
msg = "桶级探测失败（HEAD 无响应体，按状态码判断）"
raise S3Error("HeadBucket", status, code, msg)
steps.append({"name": "连接与凭据", "ok": True, "detail": "桶可访问（HEAD %s）" % cfg.bucket})
key = probe_key(cfg)
payload = b"TamaBox theme builder probe\n"
status, _, body = s3_request(cfg, "PUT", key, payload, "text/plain; charset=utf-8", "no-store")
if status >= 400:
code, msg = _parse_s3_error(body)
raise S3Error("PutObject", status, code, msg)
steps.append({"name": "写入权限", "ok": True, "detail": "已写入探针 %s" % key})
status, _, body = s3_request(cfg, "GET", key)
ok = status == 200 and body == payload
steps.append({
"name": "读回校验", "ok": ok,
"detail": "读回一致" if ok else "读回失败（HTTP %s）" % status,
})
public = _public_read(cfg.url(cfg.object_path(key)))
steps.append({
"name": "匿名可读", "ok": True,
"detail": "该路径可直接匿名访问" if public
else "匿名访问被拒 —— 桶没开公开读时正常，靠自定义域或 CDN 分发即可",
"warn": not public,
})
s3_request(cfg, "DELETE", key)
return {"ok": True, "steps": steps, "key": key}
# ---------------------------------------------------------------------------
# 上传
# ---------------------------------------------------------------------------
def upload_files(cfg, files):
if not files:
raise ValueError("没有要上传的素材")
if len(files) > 200:
raise ValueError("一次最多 200 个文件")
results = []
for f in files:
name = str(f.get("name") or f.get("key") or "?")
try:
key = full_key(cfg, f.get("key") or f.get("name"))
data = base64.b64decode(f.get("data") or "", validate=False)
if not data:
raise ValueError("内容为空")
ctype = str(f.get("contentType") or "application/octet-stream")
# 素材键里带内容版本（导出时由 id 决定），内容不会原地变化 → immutable。
# 但清单/说明这类「键不变、内容会变」的文件不能 immutable，否则一年内看不到更新，
# 所以允许逐个文件覆盖。
cache = str(f.get("cacheControl") or "public, max-age=31536000, immutable")
status, _, body = s3_request(cfg, "PUT", key, data, ctype, cache)
if status >= 400:
code, msg = _parse_s3_error(body)
results.append({"key": key, "name": name, "ok": False,
"status": status, "code": code, "error": msg})
else:
results.append({"key": key, "name": name, "ok": True, "bytes": len(data)})
except Exception as e:
results.append({"key": name, "name": name, "ok": False, "error": str(e)})
failed = [r for r in results if not r["ok"]]
return {"ok": not failed, "files": results, "failed": len(failed), "total": len(results)}
# ---------------------------------------------------------------------------
# 远端清单 / 删除
# ---------------------------------------------------------------------------
def _local(tag):
"""去掉 XML 命名空间。各家 S3 兼容实现都带 `http://s3.amazonaws.com/doc/2006-03-01/`，
个别（老 MinIO / 某些网关）又不带 —— 只比 localname 两边都能认。"""
return tag.rsplit("}", 1)[-1]
def parse_list_xml(body):
"""解析 ListObjectsV2 响应。返回 (对象数组, 下一页 token 或 None)。"""
import xml.etree.ElementTree as ET
root = ET.fromstring(body)
objects, token, truncated = [], None, False
for node in root:
name = _local(node.tag)
if name == "Contents":
row = {}
for f in node:
row[_local(f.tag)] = f.text
objects.append({
"key": row.get("Key") or "",
"size": int(row.get("Size") or 0),
"modified": row.get("LastModified") or "",
"etag": (row.get("ETag") or "").strip('"'),
})
elif name == "NextContinuationToken":
token = node.text
elif name == "IsTruncated":
truncated = (node.text or "").strip().lower() == "true"
return objects, (token if truncated else None)
def list_objects(cfg, prefix="", max_pages=20, max_keys=1000):
"""列 `<cfg.prefix>/<prefix>` 下所有对象。分页上限只是防呆，正常一个主题不到 100 个。"""
key_prefix = full_key(cfg, prefix) if str(prefix or "").strip() else (cfg.prefix + "/" if cfg.prefix else "")
objects, token, pages = [], None, 0
while pages < max_pages:
pages += 1
query = {"list-type": "2", "max-keys": str(max_keys)}
if key_prefix:
query["prefix"] = key_prefix
if token:
query["continuation-token"] = token
status, _, body = s3_request(cfg, "GET", query=query)
if status >= 400:
code, msg = _parse_s3_error(body)
raise S3Error("ListObjects", status, code or "HTTP%d" % status, msg)
page, token = parse_list_xml(body)
objects.extend(page)
if not token:
break
return {"ok": True, "prefix": key_prefix, "objects": objects, "truncated": bool(token)}
def delete_objects(cfg, keys):
"""逐个 DeleteObject。
没用批量 POST ?delete：那要额外算 Content-MD5、拼 XML body，而一次最多几十个键，
省下的往返抵不上多一条签名路径的风险。S3 的 DELETE 本身幂等（不存在的键也回 204）。
"""
if not keys:
raise ValueError("没有要删除的对象")
if len(keys) > 500:
raise ValueError("一次最多删 500 个对象")
results = []
for k in keys:
try:
key = full_key(cfg, k)
status, _, body = s3_request(cfg, "DELETE", key)
if status >= 400 and status != 404:
code, msg = _parse_s3_error(body)
results.append({"key": key, "ok": False, "status": status,
"code": code or "HTTP%d" % status, "error": msg})
else:
results.append({"key": key, "ok": True})
except Exception as e:
results.append({"key": str(k), "ok": False, "error": str(e)})
failed = [r for r in results if not r["ok"]]
return {"ok": not failed, "files": results, "failed": len(failed), "total": len(results)}
# ---------------------------------------------------------------------------
# HTTP 层
# ---------------------------------------------------------------------------
class Handler(http.server.SimpleHTTPRequestHandler):
server_version = "TamaBoxThemeBuilder/1"
def end_headers(self):
# 预览页是刚由 go test 生成的，禁止缓存，否则改了 CSS 看不到变化
self.send_header("Cache-Control", "no-store, must-revalidate")
super().end_headers()
def log_message(self, fmt, *args):
# 只报 4xx/5xx，正常请求不刷屏
status = args[1] if len(args) > 1 else ""
if str(status).startswith(("4", "5")):
sys.stderr.write(" %s\n" % (fmt % args))
def _json(self, payload, status=200):
data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
self.send_response(status)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def _read_json(self):
n = int(self.headers.get("Content-Length") or 0)
if n <= 0:
raise ValueError("请求体为空")
if n > MAX_BODY_BYTES:
raise ValueError("请求体过大（%d 字节），一次别传太多素材" % n)
return json.loads(self.rfile.read(n).decode("utf-8"))
def _same_origin(self):
"""写接口只接受「页面自己发来的」请求。
监听 0.0.0.0 之后，同网段里的另一个网页可以借访客浏览器向这里发写请求
（删对象、改前缀）。浏览器跨站请求一定带 Origin，比对它与 Host 是否同源
就能挡掉这类「借刀」调用。curl / 脚本不带 Origin，照常放行。
"""
origin = self.headers.get("Origin")
if not origin:
return True
host = (self.headers.get("Host") or "").strip().lower()
return urllib.parse.urlsplit(origin).netloc.lower() == host
def do_GET(self):
if self.path.split("?")[0] == "/api/s3/ping":
# 生成器靠它判断「当前是不是 serve.py 起的」——python -m http.server 没有这个端点。
return self._json({"ok": True, "upload": True})
return super().do_GET()
def do_POST(self):
route = self.path.split("?")[0]
if route not in ("/api/s3/test", "/api/s3/upload", "/api/s3/list", "/api/s3/delete"):
return self._json({"ok": False, "error": "未知接口 %s" % route}, 404)
if not self._same_origin():
return self._json({"ok": False, "error": "拒绝跨站写请求（Origin 与访问地址不一致）"}, 403)
try:
payload = self._read_json()
except Exception as e:
return self._json({"ok": False, "error": "请求解析失败：%s" % e})
try:
cfg = S3Config(payload.get("config") or {})
except ValueError as e:
return self._json({"ok": False, "error": str(e)})
try:
if route == "/api/s3/test":
return self._json(test_connection(cfg))
if route == "/api/s3/list":
return self._json(list_objects(cfg, payload.get("prefix") or ""))
if route == "/api/s3/delete":
return self._json(delete_objects(cfg, payload.get("keys") or []))
return self._json(upload_files(cfg, payload.get("files") or []))
except S3Error as e:
return self._json({
"ok": False, "step": e.step, "status": e.status, "code": e.code,
"error": e.message, "hint": S3_HINTS.get(e.code, ""),
})
except ValueError as e:
return self._json({"ok": False, "error": str(e)})
except Exception as e: # 兜底：别把本地服务弄崩，把异常原样告诉页面
return self._json({"ok": False, "error": "%s: %s" % (type(e).__name__, e)})
def local_addresses():
"""本机所有可用于访问的 IPv4（回环排最后）。
绑 0.0.0.0 时监听地址本身不能直接点开（浏览器访问 http://0.0.0.0 行为各家不一），
所以启动时把真实 IP 列出来，省得人去 ipconfig 里翻。
"""
out = []
try:
for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
ip = info[4][0]
if ip not in out and not ip.startswith("127."):
out.append(ip)
except Exception:
pass
try:
# 不联网也会返回默认路由网卡的地址；这一步能补上 getaddrinfo 漏掉的情况
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.connect(("8.8.8.8", 80))
ip = s.getsockname()[0]
s.close()
if ip and not ip.startswith("127.") and ip not in out:
out.append(ip)
except Exception:
pass
return out
def main():
ap = argparse.ArgumentParser(description="TamaBox 主题生成器的本地预览服务")
ap.add_argument("--port", type=int, default=8777, help="端口，默认 8777")
ap.add_argument("--host", default="0.0.0.0",
help="监听地址，默认 0.0.0.0（同一局域网都能打开）；只给本机用就写 127.0.0.1")
args = ap.parse_args()
if not os.path.isdir(os.path.join(PROJECT_ROOT, "outputs")):
sys.stderr.write(
"还没生成预览快照。先在项目根执行：\n"
" TEST_PREVIEW=1 go test ./templates -run TestGenPreview\n"
)
wildcard = args.host in ("0.0.0.0", "::")
if not wildcard and args.host not in ("127.0.0.1", "localhost", "::1"):
sys.stderr.write("⚠️ 只监听 %s，仅该地址可达。\n" % args.host)
handler = functools.partial(Handler, directory=PROJECT_ROOT)
socketserver.ThreadingTCPServer.allow_reuse_address = True
# Threading：上传一张几 MB 的图会占住连接，单线程时 iframe 预览和其它请求都得排队。
with socketserver.ThreadingTCPServer((args.host, args.port), handler) as httpd:
httpd.daemon_threads = True
print("项目根：%s" % PROJECT_ROOT)
if wildcard:
for ip in local_addresses():
print("生成器：http://%s:%d/dev/theme-builder/" % (ip, args.port))
print("生成器：http://127.0.0.1:%d/dev/theme-builder/ （本机）" % args.port)
print("提示：局域网里的其它设备用上面的 IP 地址打开；手机与电脑要在同一网段。")
sys.stderr.write(
"⚠️ 正在对局域网开放（%s:%d）。上传接口没有账号体系 —— 能打开这个端口的人，\n"
" 都能用你填的密钥往对象存储写 / 删文件。公共网络（咖啡馆、宿舍、公司网）\n"
" 请改用 --host 127.0.0.1。\n" % (args.host, args.port))
else:
print("生成器：http://%s:%d/dev/theme-builder/" % (args.host, args.port))
print("上传接口：/api/s3/test /api/s3/upload /api/s3/list /api/s3/delete")
print("Ctrl+C 停止")
try:
httpd.serve_forever()
except KeyboardInterrupt:
print("\n已停止")
if __name__ == "__main__":
main()
dev/theme-tools/export_assets.py
-219
View File
@@ -1,219 +0,0 @@
"""把 new-sakura 的内联 SVG 导出成位图，并上传到对象存储。
为什么要这一步：主题本身是纯 CSS（SVG 内联在 CSS 里），线上不依赖任何外部素材。
但对象存储上留一份位图有它的用处：
· 桶开了公开域名后，可以把 CSS 里的 url() 换成绝对地址（注意：服务端有 gzip，
内联版总传输 3.9KB 比位图版的 51KB 更小，换位图不为省流量）；
· 分享卡 / 其它非 CSS 场景只能用位图；
· 换人维护时不用去读那一长串 data URI。
用法（项目根）：
python dev/theme-tools/export_assets.py # 只导出到 outputs/sakura-assets
python dev/theme-tools/export_assets.py --upload # 导出，并把 CSS + 位图 + INSTALL.txt 传到桶里
"""
import argparse
import io
import os
import re
import sys
HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(os.path.dirname(HERE))
sys.path.insert(0, HERE)
sys.path.insert(0, os.path.join(ROOT, "dev", "theme-builder"))
import gen_new_sakura as G # noqa: E402
OUT_DIR = os.path.join(ROOT, "outputs", "sakura-assets")
# (文件名, svg 源, 导出像素宽, 高)
def assets():
p = G.LIGHT
return [
("branch-right", G.branch(p["wood"], p["light"], p["deep"], p["heart"], flip=False), 840, 640),
("branch-left", G.branch(p["wood"], p["light"], p["deep"], p["heart"], flip=True), 840, 640),
("blossom", G.blossom(p["light"], p["deep"], p["heart"]), 400, 400),
("petal", G.petal(p["light"]), 240, 336),
("pattern", G.pattern(p["pattern"]), 600, 600),
]
def render(svg, w, h, out_png):
"""用无头 Chrome 渲染成透明底 PNG。
走命令行而不是 Playwright：本机只有 node 版 playwright，python 侧没装；
而 `--default-background-color=00000000` 正好能给透明底。
⚠️ `--window-size` 不等于 CSS 视口（实测 1080 只有 985），所以窗口开大一圈
并让内容居中，再按目标尺寸从中心裁 —— 这样尺寸误差被吸收掉，不必去猜差多少。
"""
import subprocess
import tempfile
from PIL import Image
pad = 120
html = (
'<!doctype html><meta charset="utf-8">'
"<style>html,body{margin:0;background:transparent;height:100vh;"
"display:flex;align-items:center;justify-content:center}"
f"svg{{display:block;width:{w}px;height:{h}px}}</style>" + svg
)
fd, html_path = tempfile.mkstemp(suffix=".html")
os.close(fd)
with open(html_path, "w", encoding="utf-8") as f:
f.write(html)
chrome = "C:/Program Files/Google/Chrome/Application/chrome.exe"
cmd = [
chrome, "--headless=old", "--disable-gpu", "--hide-scrollbars",
"--force-device-scale-factor=1", "--default-background-color=00000000",
"--window-size=%d,%d" % (w + pad, h + pad),
"--screenshot=" + out_png,
"file:///" + html_path.replace("\\", "/"),
]
subprocess.run(cmd, check=True, capture_output=True, timeout=60)
os.remove(html_path)
img = Image.open(out_png).convert("RGBA")
cw, ch = img.size
left, top = max(0, (cw - w) // 2), max(0, (ch - h) // 2)
img.crop((left, top, left + w, top + h)).save(out_png)
def to_webp(png_path, webp_path, quality=92):
from PIL import Image
img = Image.open(png_path).convert("RGBA")
img.save(webp_path, "WEBP", quality=quality, method=6)
def read_r2(path):
cfg = {}
for line in open(path, encoding="utf-8"):
m = re.match(r'^\s*([a-z_]+)\s*=\s*"?([^"\n]*)"?\s*$', line.strip())
if m:
cfg[m.group(1)] = m.group(2).strip()
return cfg
def pack_readme(prefix, object_base, sizes):
"""生成包内 INSTALL.txt。域名与体积都写实数，避免 README 与实际脱节。"""
base = (object_base or "").rstrip("/")
total_kb = sum(v for k, v in sizes.items() if k.endswith(".webp")) / 1024
css_kb = sizes.get("new-sakura.css", 0) / 1024
urls = ""
if base:
urls = "\n公开地址（已验证可匿名 GET）\n--------------------------\n" + "\n".join(
" %s/%s" % (base, n) for n in ["new-sakura.css"] + [
"%s.webp" % k for k in ["branch-right", "branch-left", "blossom", "petal", "pattern"]])
return """new-sakura（新·樱花）主题包
============================
来源：TamaBox 仓库 static/css/themes/new-sakura.css（生成产物，勿手改）
生成：dev/theme-tools/gen_new_sakura.py（花形/位置/配色都在里面）
位图：dev/theme-tools/export_assets.py（从同一份 SVG 导出，不是另画的）
说明：docs/theme-new-sakura.md
对象前缀：%s/
文件
----
new-sakura.css 主题本体 %5.1f KB（纯 CSS，樱花是内联 SVG，零外部请求）
branch-right.webp 花枝 840x640 透明底（细端在右上）
branch-left.webp 同上镜像
blossom.webp 单朵樱花 400x400 透明底
petal.webp 单瓣 240x336 透明底
pattern.webp 平铺底纹 600x600 透明底
位图合计 %5.1f KB
怎么用
------
线上只需要 new-sakura.css：放进仓库 static/css/themes/，在 conf/app.ini 的
[theme] available 里加上 new-sakura，再重新 go build（主题 CSS 是编译期 embed，
只重启不重编不会生效）。
WebP 不是必需品 —— CSS 里的樱花是矢量，比位图清晰且没有额外请求。留着的用处：
1) 素材要单独复用：python dev/theme-tools/gen_new_sakura.py --asset-base %s
（CSS 从 %.1f KB 降到 10.6 KB，但多 5 个请求共 48.9 KB，总传输更大）
2) 非 CSS 场景（分享卡、海报）只能用位图
%s
注意
----
直连桶的 S3 endpoint（*.r2.cloudflarestorage.com）会 403，那里需要签名。
浏览器直读只能用自定义域 / r2.dev 或 CDN。
缓存：位图 1 天、CSS 5 分钟、本文件 60 秒 —— 对象键不带版本，所以**不用** immutable。
要一年长缓存，得把内容哈希写进文件名（届时 CSS 里的地址也要跟着换）。
""" % (prefix, css_kb, total_kb,
base or "https://<公开域名>/" + prefix.strip("/"), css_kb, urls)
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--upload", action="store_true", help="导出后上传到 data/r2.txt 里的桶")
ap.add_argument("--prefix", default="themes/new-sakura", help="对象键前缀，默认 themes/new-sakura")
ap.add_argument("--public-base", default="",
help="公开访问的主机（如 https://r2.example.com，不带路径）；"
"默认读 data/r2.txt 的 image_public_base 或 image_bucket_cdn_host，"
"都没有则在 INSTALL.txt 里写占位")
ap.add_argument("--r2", default=os.path.join(ROOT, "data", "r2.txt"))
args = ap.parse_args()
os.makedirs(OUT_DIR, exist_ok=True)
files, sizes = [], {}
for name, svg, w, h in assets():
png = os.path.join(OUT_DIR, name + ".png")
webp = os.path.join(OUT_DIR, name + ".webp")
render(svg, w, h, png)
to_webp(png, webp)
os.remove(png)
size = os.path.getsize(webp)
sizes[name + ".webp"] = size
print("导出 %-13s %dx%d %.1f KB" % (name, w, h, size / 1024))
files.append((name + ".webp", webp))
if not args.upload:
print("\n只导出，未上传（加 --upload 才传）。目录：%s" % OUT_DIR)
return
import base64
import serve
raw = read_r2(args.r2)
# 与 conf/app.ini 同名：image_bucket_cdn_host 只是主机名（不带 scheme）
cdn_host = raw.get("image_bucket_cdn_host", "").strip().strip("/")
public_host = (args.public_base or raw.get("image_public_base")
or ("https://" + cdn_host if cdn_host else "")).rstrip("/")
object_base = ("%s/%s" % (public_host, args.prefix.strip("/"))) if public_host else ""
cfg = serve.S3Config(dict(
endpoint=raw["image_endpoint"], region="auto", bucket=raw["image_bucket"],
prefix=args.prefix, pathStyle=True,
accessKey=raw["image_access_id"], secretKey=raw["image_access_secret"],
))
# 键名不带版本，就不配 immutable —— 否则重新导出后一年内谁看到的都还是旧图。
payload = [{"key": name, "name": name, "contentType": "image/webp",
"cacheControl": "public, max-age=86400",
"data": base64.b64encode(open(path, "rb").read()).decode()}
for name, path in files]
css_path = os.path.join(ROOT, "static", "css", "themes", "new-sakura.css")
css = open(css_path, "rb").read()
sizes["new-sakura.css"] = len(css)
payload.append({"key": "new-sakura.css", "contentType": "text/css; charset=utf-8",
"cacheControl": "public, max-age=300",
"data": base64.b64encode(css).decode()})
readme = pack_readme(args.prefix, object_base, sizes).encode("utf-8")
payload.append({"key": "INSTALL.txt", "contentType": "text/plain; charset=utf-8",
"cacheControl": "public, max-age=60",
"data": base64.b64encode(readme).decode()})
res = serve.upload_files(cfg, payload)
for r in res["files"]:
print(("OK " if r["ok"] else "FAIL ") + r["key"] + ("" if r["ok"] else " " + str(r.get("error"))))
print("\n上传 %d/%d" % (res["total"] - res["failed"], res["total"]))
if object_base:
print("公开地址：%s/" % object_base)
if __name__ == "__main__":
main()
dev/theme-tools/gen_new_sakura.py
-445
View File
@@ -1,445 +0,0 @@
"""生成 new-sakura 主题的 CSS。
为什么用脚本生成而不用生成器的图层功能：生成器的装饰层只认「图片素材」（导出时
打进 zip 或传对象存储），而这里的花瓣是**内联 SVG 的 data URI** —— 零外部请求、
任意缩放不糊、改配色只改一个色值。代价是 CSS 里会出现一长串百分号编码的 URI，
所以源 SVG 保留在本文件里，改完重跑：
python dev/theme-tools/gen_new_sakura.py
输出：static/css/themes/new-sakura.css
"""
import os
import urllib.parse
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
OUT = os.path.join(ROOT, "static", "css", "themes", "new-sakura.css")
def uri(svg):
"""转成 CSS url()。safe='' 是刻意的：连逗号、分号、括号都编码掉 ——
`--tb-deco` 是按顶层逗号切分的（internal/theme 的 TestDecoSlotCount），
URI 里留一个裸逗号就会被当成多一层的装饰。"""
return 'url("data:image/svg+xml,' + urllib.parse.quote(svg, safe="") + '")'
# ---- 花与瓣 ----------------------------------------------------------------
# 五瓣樱花：五个椭圆绕中心旋 72°，中心一团深一点的蕊。不做花瓣缺口——
# 在 30~90px 的显示尺寸上缺口只剩 2px，反而像毛边；靠五瓣轮廓就够识别。
def blossom(light, deep, heart):
petals = "".join(
f'<ellipse cx="50" cy="27" rx="14" ry="21" transform="rotate({a} 50 50)"/>'
for a in (0, 72, 144, 216, 288)
)
return (
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">'
f'<g fill="{light}">{petals}</g>'
f'<circle cx="50" cy="50" r="7.5" fill="{deep}"/>'
f'<circle cx="50" cy="50" r="3" fill="{heart}"/>'
"</svg>"
)
# 单瓣：顶端留一个 V 形缺口（樱花花瓣的标志），比整朵花更适合当"飘落"的单位。
def petal(fill):
return (
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 56">'
f'<path d="M20 1c9 0 15 8 15 18 0 5-2 9-4 12l-4-5-7 9-7-9-4 5c-2-3-4-7-4-12C5 9 11 1 20 1z" fill="{fill}"/>'
"</svg>"
)
# 枝条：一根主枝 + 两根小杈 + 五朵花 + 三片落瓣。
# 花是重复内联而不是 <use href="#f">：data URI 里的片段引用在各浏览器上
# 行为不一致（Safari 曾整朵不渲染），多几百字节换确定性。
def branch(wood, light, deep, heart, flip=False):
fl = ' transform="translate(420,0) scale(-1,1)"' if flip else ""
# 花要比枝小得多、数量多几朵。早先 5 朵 scale≈1 的花配一根细枝，缩到 300px
# 显示时是一串糖葫芦；真实樱花枝是"小碎花沿枝密布"，所以花收到 0.42~0.62。
# 第四项是旋转角：一朵朵都朝正上方会像贴纸糊上去的，真实花枝上朝向各异
blossoms = [
(302, 74, 0.62, 14), (256, 110, 0.55, -22), (214, 138, 0.60, 34), (172, 176, 0.58, -6),
(352, 42, 0.50, 48), (140, 214, 0.46, 20), (116, 246, 0.40, -32), (326, 128, 0.42, 28),
]
petals = [(272, 158, 22), (318, 150, -18), (196, 92, 40), (150, 196, -26)]
body = []
for x, y, s, rot in blossoms:
body.append(
f'<g transform="translate({x} {y}) rotate({rot}) scale({s}) translate(-50 -50)">'
'<g fill="%s">' % light
+ "".join(f'<ellipse cx="50" cy="27" rx="14" ry="21" transform="rotate({a} 50 50)"/>'
for a in (0, 72, 144, 216, 288))
+ f'</g><circle cx="50" cy="50" r="7" fill="{deep}"/>'
f'<circle cx="50" cy="50" r="2.8" fill="{heart}"/></g>'
)
for x, y, rot in petals:
body.append(
f'<g transform="translate({x} {y}) rotate({rot}) scale(0.42) translate(-20 -28)">'
f'<path d="M20 1c9 0 15 8 15 18 0 5-2 9-4 12l-4-5-7 9-7-9-4 5c-2-3-4-7-4-12C5 9 11 1 20 1z" fill="{light}"/></g>'
)
return (
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 320">'
f'<g{fl}>'
f'<path d="M2 318C74 276 112 212 176 184c62-28 102-72 146-118 26-28 52-46 82-58" '
f'fill="none" stroke="{wood}" stroke-width="4.2" stroke-linecap="round" opacity=".62"/>'
f'<path d="M176 184c-4-30 4-56 16-78M262 126c16-28 32-48 46-58" '
f'fill="none" stroke="{wood}" stroke-width="2.8" stroke-linecap="round" opacity=".5"/>'
+ "".join(body) + "</g></svg>"
)
# 平铺底纹：极淡的小花 + 落瓣。
# 密度是刻意的：最早一版放了 2 朵花 + 2 片瓣并且 260px 平铺，页面上读出来是
# 「整齐的包装纸」——因为每个元素都在固定格点上重复。现在只留 1 朵 + 2 片，
# 尺寸放大到 300px 且各自错位，平铺时才看不出周期。
def pattern(light, strong=False):
"""平铺底纹。strong 给窄屏用：那里装饰层全关，底纹是屏幕上唯一的樱花，
照桌面那套 0.18~0.34 的透明度在 390px 上基本看不出来（实测截图接近纯粉底）。"""
k = 1.9 if strong else 1.0
one = (
'<g fill="%s">' % light
+ "".join(f'<ellipse cx="50" cy="27" rx="14" ry="21" transform="rotate({a} 50 50)"/>'
for a in (0, 72, 144, 216, 288))
+ "</g>"
)
petal_path = ('<path d="M20 1c9 0 15 8 15 18 0 5-2 9-4 12l-4-5-7 9-7-9-4 5'
'c-2-3-4-7-4-12C5 9 11 1 20 1z" fill="%s"/>')
o = lambda v: min(0.92, round(v * k, 2))
return (
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 300">'
f'<g transform="translate(96 84) scale(0.34) translate(-50 -50)" opacity="{o(0.34)}">{one}</g>'
f'<g transform="translate(236 208) rotate(28) scale(0.26)" opacity="{o(0.24)}">'
+ (petal_path % light) +
"</g>"
f'<g transform="translate(188 52) rotate(-34) scale(0.2)" opacity="{o(0.18)}">'
+ (petal_path % light) +
"</g>"
"</svg>"
)
# ---- 一套素材（浅色 / 深色各一组色） ---------------------------------------
LIGHT = dict(
light="#f7bcd0", deep="#e989aa", heart="#fdf6f8",
wood="#9a7a70", pattern="#f2bfd0",
)
DARK = dict(
light="#f0a0b8", deep="#c96a8b", heart="#2c2227",
wood="#a8837a", pattern="#7a4e5f",
)
def uris(p, asset_base=""):
"""asset_base 非空 -> 引用对象存储上的位图（键名与 export_assets.py 的产物一致）。
内联 SVG 是默认：gzip 后约 3.9KB、零额外请求。位图版 CSS 只有 10.6KB，但要多个
5 个请求共 ~49KB，总传输反而更大 —— 它存在的理由是素材能被非 CSS 场景复用。
换之前先确认桶已对公网可读（自定义域或 r2.dev），否则主题会整片 403。
"""
if asset_base:
b = asset_base.rstrip("/")
return {
"blossom_l": 'url("%s/blossom.webp")' % b,
"petal_l": 'url("%s/petal.webp")' % b,
"branch_l": 'url("%s/branch-left.webp")' % b,
"branch_r": 'url("%s/branch-right.webp")' % b,
"pattern": 'url("%s/pattern.webp")' % b,
"pattern_narrow": 'url("%s/pattern.webp")' % b,
}
return {
"blossom_l": uri(blossom(p["light"], p["deep"], p["heart"])),
"petal_l": uri(petal(p["light"])),
"branch_l": uri(branch(p["wood"], p["light"], p["deep"], p["heart"], flip=True)),
"branch_r": uri(branch(p["wood"], p["light"], p["deep"], p["heart"], flip=False)),
"pattern": uri(pattern(p["pattern"])),
"pattern_narrow": uri(pattern(p["pattern"], strong=True)),
}
NONE10 = "none, none, none, none, none, none, none, none, none, none"
AUTO10 = "auto, auto, auto, auto, auto, auto, auto, auto, auto, auto"
TOPLEFT10 = ("left top, left top, left top, left top, left top, left top, left top, "
"left top, left top, left top")
def deco(layers):
"""layers: [(var, size, position)]，不足 10 槽补 none。"""
items, sizes, poss = [], [], []
for var, size, pos in layers:
items.append(var)
sizes.append(size)
poss.append(pos)
pad = 10 - len(layers)
items += ["none"] * pad
sizes += ["auto"] * pad
poss += ["left top"] * pad
return (", ".join(items), ", ".join(sizes), ", ".join(poss))
# ---- 每个页面一套位置 ------------------------------------------------------
# 位置一律两值（`关键字 ± 偏移`）。百分比相对「容器 − 图片」，写 calc 更可控；
# 这里用 left/right + % 与 px 偏移，保证换视口时花还贴在角落而不是飘到内容上。
SCOPES = {
"global": [
("var(--sk-branch-r)", "auto 280px", "right -16px bottom -22px"),
("var(--sk-blossom)", "auto 88px", "left 6% top 12%"),
("var(--sk-petal)", "32px", "left 14% top 24%"),
("var(--sk-petal)", "26px", "right 16% top 8%"),
],
"box": [
# 枝的细端在右上、粗端朝左下：放在右上角时"从角上垂下来"，
# 尺寸收到 300px 才会有枝形 —— 390px 时可见部分只剩一团花（第一次就是这个问题）
# top 从 -16px 收到 26px：顶栏改透明后，700~760px 宽度下枝头会正好压在"登录"上。
# 顶栏高 60px、外边距 20px，26px 起笔即落在顶栏下沿之上，宽屏仍保留"从右上角长出"。
("var(--sk-branch-r)", "auto 300px", "right -24px top 26px"),
("var(--sk-blossom)", "auto 80px", "left 5% bottom 16%"),
("var(--sk-petal)", "34px", "left 14% bottom 32%"),
("var(--sk-petal)", "24px", "right 22% bottom 8%"),
("var(--sk-blossom)", "auto 52px", "right 6% bottom 6%"),
],
"question": [
("var(--sk-branch-l)", "auto 300px", "left -34px bottom -24px"),
("var(--sk-blossom)", "auto 86px", "right 7% top 11%"),
("var(--sk-petal)", "30px", "right 17% top 24%"),
("var(--sk-petal)", "24px", "left 11% top 7%"),
],
"admin": [
# 列表页卡片几乎占满宽度，右侧的花会整个被卡片盖住 —— 只往左侧留白放
("var(--sk-branch-l)", "auto 260px", "left -28px top -24px"),
("var(--sk-blossom)", "auto 70px", "left 3% bottom 7%"),
("var(--sk-petal)", "26px", "left 11% bottom 15%"),
],
"profile": [
("var(--sk-branch-r)", "auto 280px", "right -28px bottom -24px"),
("var(--sk-blossom)", "auto 66px", "left 6% top 9%"),
("var(--sk-petal)", "28px", "left 15% top 19%"),
("var(--sk-petal)", "22px", "left 5% top 28%"),
],
"vote": [
("var(--sk-branch-l)", "auto 280px", "left -30px top -20px"),
("var(--sk-blossom)", "auto 78px", "right 8% top 16%"),
("var(--sk-petal)", "28px", "right 18% top 27%"),
("var(--sk-blossom)", "auto 52px", "right 6% bottom 8%"),
],
# 窄屏：卡片占满宽度，左右只剩 ~16px 边距，花枝放哪儿都糊在字上。
# 实测底纹铺在 16px 边距里根本落不到花 —— 花朵在格子里的位置固定在 x≈58，
# 所以只在「顶栏与卡片之间」那条 30px 的横带里放几朵小的，其余交给加强底纹。
# 试过在「顶栏与卡片之间」那条 ~35px 的带子里放小樱花：box 页卡片从 y=122 起还行，
# question/admin 页卡片从 y=110 起就把它切掉半个，结果是贴在卡片边上的粉色碎块。
# 手机上没有可靠的留白，干脆不放装饰层 —— 观感交给配色与底纹（加强版 pattern）。
"narrow": [],
}
def scope_block(prefix, layers, indent=" "):
img, size, pos = deco(layers)
return (
f"{prefix} {{\n"
f"{indent}--tb-deco: {img};\n"
f"{indent}--tb-deco-size: {size};\n"
f"{indent}--tb-deco-position: {pos};\n"
"}"
)
def build(asset_base=""):
u = uris(LIGHT, asset_base)
d = uris(DARK, asset_base)
vars_light = "\n".join([
f" --sk-blossom: {u['blossom_l']};",
f" --sk-petal: {u['petal_l']};",
f" --sk-branch-l: {u['branch_l']};",
f" --sk-branch-r: {u['branch_r']};",
])
vars_dark = "\n".join([
f" --sk-blossom: {d['blossom_l']};",
f" --sk-petal: {d['petal_l']};",
f" --sk-branch-l: {d['branch_l']};",
f" --sk-branch-r: {d['branch_r']};",
])
light_block = f"""html[data-theme-style="new-sakura"] {{
--tb-bg: #fdf6f8;
--tb-surface: #ffffff;
--tb-surface-2: #fdf0f4;
--tb-surface-hover: #fff7fa;
/* 顶栏做磨砂玻璃：樱花从角落长出来，实色顶栏会把它齐刷刷切一段；但也不能给
transparent —— 顶栏会"消失"，导航失去依托，文字直接压在花纹上。留 28% 的透光。
模糊由下面「组件微调」里的 backdrop-filter 加（令牌只能给颜色）。 */
--tb-navbar: rgba(253, 246, 248, 0.72);
--tb-border: #f3dde5;
--tb-text: #3a2c31;
--tb-text-secondary: #6d555d;
/* 5.27:1（底色）/ 5.62:1（卡片），踩住 AA 下限 */
--tb-text-muted: #77626a;
/* #c14a72 在粉底上只有 4.39:1，同色相压深到 #b8436a = 4.87:1 */
--tb-primary: #b8436a;
--tb-primary-weak: rgba(184, 67, 106, 0.12);
--tb-on-primary: #ffffff;
--tb-shadow: 0 1px 2px rgba(150, 80, 105, 0.05), 0 12px 28px -18px rgba(150, 80, 105, 0.22);
--tb-shadow-hover: 0 1px 2px rgba(150, 80, 105, 0.07), 0 18px 40px -20px rgba(150, 80, 105, 0.30);
/* 花与瓣都是内联 SVG（data URI），没有外部素材 —— 所以这个主题不需要对象存储。
--sk-* 是花材的别名：同一个 URI 只在这里出现一次，下面各页面作用域引用变量，
否则 6 套位置会把 4 个 data URI 重复 20 多次，文件直接翻倍。 */
{vars_light}
/* 整页底纹：极淡的花与落瓣，260px 平铺。压在白底上只是一层纸纹，
不参与构图（真正的樱花由下面的装饰层负责）。 */
--tb-page-image: none;
--tb-page-pattern: {u['pattern']};
--tb-page-pattern-size: 300px 300px;
"""
# 全局默认位置：写在同一个块里（未单独配置的页面沿用这套）
body = light_block + deco_block_inline(SCOPES["global"]) + "}\n"
for key in ("box", "question", "admin", "profile", "vote"):
body += "\n" + scope_block(
f'html[data-theme-style="new-sakura"][data-page-scope="{key}"]', SCOPES[key]) + "\n"
dark_block = f"""
html[data-theme="dark"][data-theme-style="new-sakura"] {{
--tb-bg: #221a1e;
--tb-surface: #2c2227;
--tb-surface-2: #372a30;
--tb-surface-hover: rgba(255, 147, 180, 0.10);
--tb-navbar: rgba(34, 26, 30, 0.72);
--tb-border: #47333b;
--tb-text: #f3e6ea;
--tb-text-secondary: #c9aeb8;
/* 5.82:1（底色）/ 5.26:1（卡片） */
--tb-text-muted: #ab9099;
--tb-primary: #ff93b4;
--tb-primary-weak: rgba(255, 147, 180, 0.16);
--tb-on-primary: #1b1014;
--tb-shadow: 0 1px 2px rgba(0, 0, 0, 0.34), 0 12px 28px -18px rgba(0, 0, 0, 0.58);
--tb-shadow-hover: 0 1px 2px rgba(0, 0, 0, 0.40), 0 18px 40px -20px rgba(0, 0, 0, 0.68);
{vars_dark}
/* 深色不铺底纹：浅粉花瓣压在深底上会变成一层噪点 */
--tb-page-image: linear-gradient(180deg, #251c21 0%, #221a1e 62%, #1e171b 100%);
--tb-page-pattern: none;
""" + deco_block_inline(SCOPES["global"], indent=" ") + "}\n"
for key in ("box", "question", "admin", "profile", "vote"):
dark_block += "\n" + scope_block(
f'html[data-theme="dark"][data-theme-style="new-sakura"][data-page-scope="{key}"]',
SCOPES[key]) + "\n"
# 作用域块的选择器是 html[data-theme-style][data-page-scope="box"]（特异性 0,2,1），
# 比 html[data-theme-style] （0,1,1）高 —— 光写一条压不住，窄屏照样是桌面版装饰。
# 所以用同等特异性的通配属性选择器再写一遍，靠「在文件里更晚」取胜；
# 深色作用域块是 0,3,1，还得再补一条。
narrow_rules = ""
for sel in (
'html[data-theme-style="new-sakura"][data-page-scope]',
'html[data-theme="dark"][data-theme-style="new-sakura"]',
'html[data-theme="dark"][data-theme-style="new-sakura"][data-page-scope]',
):
narrow_rules += " %s {\n%s }\n" % (
sel, deco_block_inline(SCOPES["narrow"], indent=" "))
narrow = (
"\n@media (max-width: 640px) {\n"
' html[data-theme-style="new-sakura"] {\n'
+ deco_block_inline(SCOPES["narrow"], indent=" ")
+ " /* 手机上装饰层整个收掉（卡片占满宽度），樱花只能由底纹承担：\n"
" 换成加强版 + 缩小格子，否则 390px 上看就是一片纯粉 */\n"
" --tb-page-pattern: %s;\n" % u["pattern_narrow"]
+ " --tb-page-pattern-size: 180px 180px;\n"
" }\n"
+ narrow_rules
+ "}\n"
)
return HEADER + body + dark_block + narrow + FOOTER
def deco_block_inline(layers, indent=" "):
img, size, pos = deco(layers)
return (
f"{indent}--tb-deco: {img};\n"
f"{indent}--tb-deco-size: {size};\n"
f"{indent}--tb-deco-position: {pos};\n"
)
HEADER = """/* 新·樱花（new-sakura）：纯 CSS 樱花，不依赖任何图片素材。
和已有的 sakura 主题的区别：sakura 是"粉底 + 网点"的静态配色；这里把樱花本身
做成了可摆放的装饰层 —— 整朵花、带缺口的花瓣、带枝的花朵树，全部是内联 SVG
的 data URI，所以：换颜色只改一个色值、任意视口不糊、没有额外请求、不需要对象存储。
每个页面一套位置（--tb-deco / -size / -position 三组各 10 槽，必须等长）：
global 未单独配置的页面 右下花枝 + 左上两瓣
box 箱主页 右上花枝垂下 + 左下花与落瓣
question 问题页 左下花枝 + 右上花与落瓣
admin 题目列表 左上花枝（只压顶部边距，不抢列表）
profile 设置页 右下花枝 + 左侧竖排小瓣
vote 投票页 左上花枝 + 右侧花与落瓣
≤640px 一律只留角落两朵小的 —— 卡片占满宽度后枝条会糊在字上
位置一律「两值 + 关键字」，不用三值语法（三值里混用 left/bottom 关键字是非法组合，
整条声明会作废，花瓣会静默回到左上角）。
生成：python dev/theme-tools/gen_new_sakura.py（改花形/位置请改那个脚本，别手改这里）
*/
"""
FOOTER = """
/* 组件微调（仅外观）：顶栏与粉底融在一起后，UIkit 默认的 #999 链接色偏淡 */
html[data-theme-style="new-sakura"] .uk-navbar-nav > li > a {
color: var(--tb-text-secondary);
}
html[data-theme-style="new-sakura"] .uk-navbar-nav > li > a:hover {
color: var(--tb-primary);
}
/* 信息提示条：UIkit 的浅蓝在樱粉底上是唯一的冷色块，换成主色的弱化底 */
html[data-theme-style="new-sakura"] .uk-alert-primary {
background-color: var(--tb-primary-weak);
color: #9c3356;
}
html[data-theme="dark"][data-theme-style="new-sakura"] .uk-alert-primary {
color: #ffb3c8;
}
/* 顶栏磨砂：半透明底由 --tb-navbar 给，模糊必须在这里加（令牌只能是颜色值）。
和手机底栏一样是「半透明 + 模糊」，不是全透明 —— 顶栏得看得见，只是后面透得出花。 */
html[data-theme-style="new-sakura"] .uk-navbar-container:not(.uk-navbar-transparent) {
-webkit-backdrop-filter: blur(12px);
backdrop-filter: blur(12px);
}
/* 手机底栏：base.css 写死 rgba(255,255,255,.92)，压在粉底上是一条白杠，跟背景脱开 */
html[data-theme-style="new-sakura"] #tb-mobile-utils {
background: rgba(253, 246, 248, 0.92);
}
html[data-theme="dark"][data-theme-style="new-sakura"] #tb-mobile-utils {
background: rgba(34, 26, 30, 0.92);
}
"""
if __name__ == "__main__":
import argparse
ap = argparse.ArgumentParser(description="生成 new-sakura 主题 CSS")
ap.add_argument("--asset-base", default="",
help="引用对象存储位图的前缀，如 https://r2.example.com/themes/new-sakura；"
"留空 = 内联 SVG（默认）")
ap.add_argument("--out", default=OUT, help="输出路径")
args = ap.parse_args()
css = build(args.asset_base)
with open(args.out, "w", encoding="utf-8", newline="\n") as f:
f.write(css)
print("已生成 %s（%.1f KB）%s" % (args.out, len(css.encode()) / 1024,
" [位图版]" if args.asset_base else " [内联 SVG]"))
dev/webpstub/webp.go
+3 -10
View File
@@ -1,7 +1,6 @@
// webpstub（package webp）是 chai2010/webp 的本地编译桩：仅用于在缺少 libwebp 的
// Windows 沙箱中通过 `go build -overlay` 替换 chai2010/webp 的全部源文件，
// 从而让真实的 internal/storage/s3.go（而非桩）参与完整类型检查。
// 仅覆盖项目实际用到的 API。
// Windows 沙箱中通过 `go build -overlay` 对依赖 internal/storage 的包做完整
// 类型检查。API 只覆盖项目实际用到的 Encode/Options。
package webp
import (
@@ -9,19 +8,13 @@ import (
"io"
)
// Options 与 github.com/chai2010/webp 的 Options 字段保持兼容。
// Options 与 github.com/chai2010/webp 的 Options 字段保持兼容（项目仅用 Quality）。
type Options struct {
Lossless bool
Quality float32
Exact bool
}
// Encode 是 webp.Encode 的签名兼容桩（类型检查期间不会被真正调用）。
func Encode(w io.Writer, m image.Image, o *Options) error {
return nil
}
// DecodeConfig / Decode 保留解码入口签名，供 s3.go 的 image.Decode 分派路径类型检查。
func DecodeConfig(r io.Reader) (image.Config, error) { return image.Config{}, nil }
func Decode(r io.Reader) (image.Image, error) { return nil, nil }
docs/cli.md
-434
View File
@@ -1,434 +0,0 @@
# TamaBox 命令行操作手册（站方运维）
本项目**没有管理后台**：站方的全部运营动作只落在三类操作上 —— **CLI 命令 / 邮件告警 / 改配置后重启**。
这份文档只讲 CLI，覆盖处置、举报取证、批量隐藏与账号管理。
---
## 0. 前置
### 二进制从哪里来
```bash
# 仓库根目录构建（与 Dockerfile 是两条不同入口，命令列表必须双向同步）
go build -o tamabox .
# Docker 用的是这一条
go build -o NekoBox ./cmd/
```
两处都注册在同一份 `app.Commands` 列表中。**新增命令时必须同时改 `tamabox.go` 和 `cmd/tamabox.go`**，
否则会出现「本机二进制有、线上没有」（或反之），典型报错是 `No help topic for '<cmd>'`。
⚠️ **替换二进制不等于生效**：`go build -o tamabox .` 只改磁盘文件，正在运行的进程仍是旧映像。
换完之后必须重启（systemd / supervisor / 手动拉起），否则改了代码也看不到变化。
另外 `./tamabox web` 在前台立即返回，通常是端口被旧进程占着：
```bash
ps -eo pid,lstart,cmd | grep '[t]amabox' # 看进程启动时间，与二进制 mtime 比对
```
确认手头二进制包含全部命令：
```bash
./tamabox --help | sed -n '/COMMANDS/,/GLOBAL/p'
# web / censor / uid / ban / restore / reports / restrict / unrestrict / hide-public / honeypot / backup / restore-images
```
> 想确认某个字符串有没有编进二进制，**不要用 `strings`** —— 它默认只输出可打印 ASCII，
> UTF-8 中文整段被丢弃，`strings x | grep 中文` 恒为 0。
> 用 `grep -ac "中文字符串" x`。
### 配置文件
CLI 与 `web` 读同一份配置，路径由环境变量指定：
```bash
NEKOBOX_CONFIG_PATH=/path/to/app.ini ./tamabox reports --domain xxx
```
必要条件（缺失会直接启动失败）：
- `app.external_url`
- `server.salt`、`server.xsrf_key`
- `[database]` 段的 type / host / port / user / password / name
⚠️ CLI 启动时会跑 **AutoMigrate**（与 web 相同）。这是特性也是风险：迁移有问题时连只读的
`reports` 都跑不起来。做重要操作前先 `pg_dump`。
### 操作前先备份
```bash
pg_dump -Fc <dbname> > before-$(date +%F-%H%M).dump
```
---
## 1. 命令总览
| 命令 | 作用 | 是否改数据 | 典型用途 |
|---|---|---|---|
| `reports` | 举报取证 / 待处理列表 / 全站统计 | 否 | 处置前看证据 |
| `restrict` | 施加处置（L1–L4） | 是 | 停止分发、冻结发布、停用页面 |
| `unrestrict` | 撤销全部生效中处置并发解除通知 | 是 | 解封、误操作回滚 |
| `hide-public` | 批量把公开回答转为私密 | 是 | 清理存量挂人内容 |
| `ban` | 永久封禁（删用户+内容） | 是（不可逆） | 严重违规账号 |
| `restore` | 恢复已停用账号 | 是 | 用户申诉后恢复 |
| `censor` | 重新审核历史内容 | 是 | 审核规则变更后复检 |
| `uid` | 为用户生成/补齐 uid | 是 | 数据修复 |
| `honeypot` | 扫描器诱捕取证（假登录页） | 部分是（`prune` / `purge-creds`） | 看谁在扫、拿到了什么字典 |
| `backup` | 备份 PostgreSQL 与配置 bucket 的全部 R2 对象 | 写本地备份目录 | 灾难恢复前留档 |
| `restore-images` | 校验并恢复 R2 图片及元数据 | 是（除 `--dry-run`） | 图片灾难恢复、隔离恢复演练 |
| `web` | 启动 Web 服务 | — | 生产入口 |
除 `reports`、`honeypot hits/stats/paths/size` 外，既有运营写操作要求交互式输入大写 `YES` 确认；
脚本化时加 `--yes`。注意 `honeypot prune` / `purge-creds` 的确认词是 **`yes`**（小写）。
`restore-images` 不做交互确认：实际写入必须显式提供 `--yes`，`--dry-run` 除外。
---
## 2. `reports` —— 处置前的取证
三种互斥用法（`--stats` / `--pending` 优先于 `--email/--domain`）。
### 2.1 单个箱主的证据包
```bash
./tamabox reports --domain 52mxtx1314
./tamabox reports --email user@example.com --days 90 --limit 50
```
输出包含：
- **当前处置**：级别、到期时间、原因
- **近 N 天：被举报 X 条 / 公开回答 Y 条（累计，Z%）；举报 W 次，其中待处理 V 次**
- **被举报条目**：按举报数降序，带题号、内容前 48 字与状态（`待处理 N` / `已处理`）
- **历史处置**：每条的时间、级别、原因、状态（生效中 / 已撤销 / 已到期）
口径（容易误读，务必看清）：
- 分子 = 窗口内**被举报的条目数**（不是举报次数）。同一条被 5 个人举报只算 1 条。
- 分母 = 该箱主**当前累计**的公开回答数，**不是**窗口内产出。
所以 L2 收窄公开之后，分母会变小，比例可能超过 100% —— 这不是 bug，是分母口径问题。
判断「组织化挂人」时优先看**绝对条数**与**指涉对象分布**，比例只作参考。
- 已删除的提问不计入（`deleted_at IS NULL`）。
### 2.2 全站待处理举报
```bash
./tamabox reports --pending --limit 50
```
按箱主分组列出所有 `status = pending` 的举报（不受 30 天窗口限制，方便清理积压）。
### 2.3 全站维度统计（识别「举报被武器化」）
```bash
./tamabox reports --stats --days 7
```
输出两个 Top 10：
- **被举报最多的箱主**（含 domain / 昵称 / 待处理举报数）
- **举报来源 IP 最多**（同一 IP 反复举报同一批内容）
怎么读：
| 现象 | 更可能是 |
|---|---|
| 多个 IP 打同一个箱主，且内容指向多个不同对象 | 组织化挂人 |
| 少量 IP 打多个不同箱主 | 举报被武器化（报复性举报） |
| 同一 IP 单点爆发 | 脚本刷量（已由验证码 + 唯一索引限制） |
⚠️ 统计只覆盖**待处理**举报，且最长回溯 30 天（超期未处理的举报会自动退出统计池）。
### 2.4 举报计数的前提：客户端 IP
举报去重键是 `(question_id, reporter_ip)`，计数与统计全部依赖真实客户端 IP。
- 站点在反向代理 / CDN 之后时，**必须**在 `[security]` 配置 `trust_proxy = true`，
并按需配置 `trusted_proxies`。
- 若 `trust_proxy = false` 而站点实际在代理后，所有访客会被识别成同一个代理 IP →
每条内容最多只有 1 条举报，阈值告警永远不会触发。
- 验证方法：从两个不同网络各举报一次，然后 `reports --pending` 看是否出现两个不同 IP。
---
## 3. `restrict` —— 分级处置
```bash
./tamabox restrict --domain <domain> --level L1 --days 7 --reason "组织挂人投稿"
./tamabox restrict --email <email> --level L3 --days 14 --reason "复发" --yes
```
参数：
| 参数 | 说明 |
|---|---|
| `--domain` / `--email` | 二选一；都填时按 email 查 |
| `--level` | `L1` / `L2` / `L3` / `L4`，默认 L1，大小写敏感 |
| `--days` | 生效天数，从当前时间起算，必须 > 0 |
| `--reason` | **必填**，写入审计记录（**不会展示给用户**，只用于内部留痕） |
| `--yes` | 跳过 `YES` 确认 |
| `--force` | `--days` 超过 90 天时**必须**加，否则直接拒绝执行 |
| `--no-notify` | 不给箱主发处置通知邮件（默认发） |
### 异常时长与二次确认
`--days` 不设硬上限（长期封禁是真实需求），但超过 **90 天**时：
- 不加 `--force` → 直接报错退出（多打一个 0 不会被执行）
- 交互模式下还要**再输入一次级别名**（如 `L3`）才继续
- 脚本里 `--force --yes` 两个显式开关即构成两次确认
### 处置通知
处置生效后会自动给箱主发一封邮件（按箱主自己的界面语言，四语言齐全），内容只有：
- 级别与级别名称（如 L3 冻结发布）
- 到期时间
- 社区规则链接
- 申诉渠道（页脚「找站长」）
**邮件里不包含 `--reason` 原文，也不引用被举报内容** —— 沿用公告模板的口径：只写级别、期限、依据。
需要「静默止血」（不惊动对方、避免其转移阵地）时加 `--no-notify`。
邮件发送失败**不会回滚处置**：只打一条 warn 并在终端提示，处置仍然生效。
### 级别语义
| 级别 | 名称 | 实际效果 | 生效点 |
|---|---|---|---|
| **L1** | 停止分发 | 单题/整箱分享卡不可生成；从首页、探索、标签检索、随机位摘除；热门标签不再出现 | `share.go`、`users.go` |
| **L2** | 收窄公开 | L1 全部 + 新回答强制私密（单条 UPDATE 同时写回答与 `is_private`）+ 禁止「设为公开」+ 禁止回答追问 | `question.go`、`follow_up.go` |
| **L3** | 冻结发布 | L2 全部 + 禁止回答（**仍可收信**） | `question.go` |
| **L4** | 页面停用 | 整个 `/_/{domain}` 全部 302 到 `/restricted`（单题、私聊、分享卡、JSON 列表接口一并挡住） | `page.go` Pager + `ListAPI` |
设计要点：
- **L3 不禁收信**。伤害来自「发布」，剥夺收信能力没有治理收益，还会给对方「平台封口」的说法。
- **到期自动解除**：判定是 `expires_at > now()`，没有定时任务，也不需要手工解封。
- **替换语义**：同一用户再次 `restrict` 会先撤销旧的生效记录再写新的，任何时刻只有一条生效。
升级（L1→L3）与降级（L3→L1）都走这条路径。
- **处置期间审核严格度锁定为最高档**（`strict`），箱主无法自行改档；解禁后自动恢复他原本的设置
（`users.moderation_strictness` 全程未被改写）。
### 副作用（需要提前知道）
- 处置期间箱主在自己后台能看到橙色条幅（级别 + 到期日 + 规则页链接）。
- **L1 就强制 strict**：L1 只停分发、内容仍能发布，但审核已按最严处理，
正常的吐槽式提问也可能被拦。若线上发现大面积误拒，把 `moderation.EffectiveStrictness`
改成「L1 沿用原设置」即可（一行）。
- **处置会给箱主发通知邮件**（见上）。若用 `--no-notify` 跳过，箱主只剩登录后的橙色条幅。
- 邮件发送依赖 `[mail]` 段的 SMTP 配置；未配置时处置仍会生效，但终端会提示发送失败。
---
## 4. `unrestrict` —— 撤销
```bash
./tamabox unrestrict --domain <domain>
./tamabox unrestrict --email <email> --no-notify
```
- 把该用户**所有生效中**的处置写 `revoked_at`（保留记录，不删除，审计可追溯）。
- 幂等：没有生效中处置时输出「没有生效中的处置，无需操作」。
- 撤销后：页面/发布/分享卡立即恢复；`hide-public` 已经转为私密的内容**不会**自动变回公开，
需要箱主自己逐条「设为公开」。
- **会给箱主发一封「限制已解除」通知**（四语言，与处置通知同一模板，无申诉段），
正文里明确写了「私密内容不会自动恢复」。`--no-notify` 可跳过。
⚠️ **到期自动解除不会发信**：那个判定是读表时比较 `expires_at`，没有定时任务。
如果希望「到期也通知」，只能靠 `unrestrict` 手工解封，或将来加个调度器。
---
## 5. `hide-public` —— 清理存量内容
```bash
# 最推荐：只隐藏「有未处理举报」的公开回答
./tamabox hide-public --domain <domain> --only-reported
# 全部公开回答（激进的兜底）
./tamabox hide-public --domain <domain>
# 只处理最近 30 天
./tamabox hide-public --domain <domain> --only-reported --since 30
```
| 参数 | 说明 |
|---|---|
| `--only-reported` | 只处理有 `pending` 举报的题目 |
| `--since N` | 只处理最近 N 天创建的题目；0 = 不限 |
| `--yes` | 跳过确认 |
行为：
- 只动「公开且已回答」的题（`answer != '' AND is_private = false`），不碰私密与未回答。
- 执行前打印总数 + 最新 10 条预览。
- **可逆**：只改可见性，箱主可逐条改回公开（但该箱主处于 L2 及以上时改不回去）。
- 隐藏成功后自动把相关 `pending` 举报标记为 `accepted`，让它们退出告警统计池。
- 单独用它不足以「停止分发」，建议配合 `restrict --level L1`。
---
## 6. 账号管理（`ban` / `restore`）
```bash
# 永久封禁：物理删除用户与其内容，邮箱释放。不可恢复。
./tamabox ban --email user@example.com --yes
./tamabox ban --domain xxx --yes
# 恢复「自助停用」的账号（软删除行），可同时重置密码
./tamabox restore --email user@example.com
./tamabox restore --email user@example.com --password 'NewPassw0rd' --yes
```
两者的区别（涉及唯一索引，容易踩）：
- **停用（可恢复）**：内容物理删除 + **用户行软删除**。邮箱/域名继续被占用是**有意为之**，
恢复靠 `restore`。
- **封禁（不可恢复）**：内容物理删除 + **用户行物理删除**，邮箱立即可重新注册。
- `restore --password` 必须在恢复之后执行，否则改不到（普通作用域查不到软删除行）。
---
## 7. `honeypot` —— 扫描器取证
> 设计取舍、凭据存储格式、部署要点见 [honeypot.md](honeypot.md)。这里只列命令。
| 子命令 | 作用 | 改数据 |
|---|---|---|
| `hits` | 列出捕获到的凭据（时间倒序，密码默认脱敏） | 否 |
| `stats` | 来源排行（IPv6 按 /64 聚合）+ 路径排行（库）+ 凭据排行（文件） | 否 |
| `paths` | 列出当前生效的诱饵路径（按伪装家族汇总） | 否 |
| `size` | 表行数、磁盘占用、凭据文件体积 | 否 |
| `prune` | 按保留期清元数据 + 凭据文件 | 是 |
| `purge-creds` | 删除旧版遗留的明文凭据列（**不可逆**） | 是 |
```bash
./tamabox honeypot hits --since 7d --limit 50
./tamabox honeypot hits --ip 203.0.113.9 --show-password
./tamabox honeypot stats --days 7
./tamabox honeypot paths
./tamabox honeypot size
./tamabox honeypot prune --days 30
./tamabox honeypot purge-creds
```
要点：
- **凭据不入库**。用户名/密码只写在 `data/honeypot-creds/creds-YYYY-MM-DD.jsonl`
（目录 0700、文件 0600），数据库里只有 IP / 路径 / UA / 是否封禁这些元数据。
所以 `hits` / `paths` **不连数据库**，DB 挂了也能查。
- 密码默认脱敏（保留首尾各 1 位）。终端输出常被贴进工单或截图，`--show-password` 只在确有取证需要时开。
- `hits` / `stats` 里的 `ip` 是**精确**客户端地址；封禁用的是 `shared.LimitKey` 折叠后的键
（IPv6 为 `/64` 前缀）。两者在 IPv6 下不一致是正常的，别拿邮件里的精确地址去对封禁键。
- `purge-creds` 用于清掉早期版本存在 `honeypot_hits` 上的明文列（AutoMigrate 不删既有列）。
执行前先 `pg_dump`；它只处理当前库，**历史备份与从库里的明文需要自行清理**。
- 封禁语义：GET 探测走常规阈值（默认 10 次 / 60 秒），**提交凭据才一次即封**。
所以「扫了几十次怎么没封」不是 bug —— 见 [honeypot.md](honeypot.md) 的「两条封禁路径」。
---
## 8. `backup` / `restore-images` —— 数据库与 R2 图片
### 8.1 备份
```bash
# 数据库 + 配置 bucket 的全部对象
./tamabox backup --output /var/backups/tamabox
# 只备份对象，或只备份数据库
./tamabox backup --images-only --output /var/backups/tamabox
./tamabox backup --db-only --output /var/backups/tamabox
```
图片备份使用**空前缀**分页列举配置 bucket 的全部对象，不再只查 `tamabox/`。根日期 key、
`picture/`、`tamabox/` 和静态资源都会按原 key 保存到 `<output>/images/`。
备份会先完成全部分页 List、key 与本地路径预检，再开始下载；非法路径、目录 key、文件/目录碰撞会中止备份。
`images-manifest.json` 记录实际下载字节的 `size`、`sha256`，以及 GET 返回的 `etag`、
`content_type`、`cache_control`。对象与 manifest 都采用临时文件原子落盘；下载流中断会整对象重试，
最终失败不会留下 `.part`。空 bucket 的 manifest 是 `[]`。
### 8.2 恢复与隔离演练
```bash
# 校验全部本地文件并检查默认防覆盖，不写远端
./tamabox restore-images --input /var/backups/tamabox --dry-run
# 实际恢复到原 key；必须显式 --yes
./tamabox restore-images --input /var/backups/tamabox --yes
# 明确允许替换已存在对象
./tamabox restore-images --input /var/backups/tamabox --yes --overwrite
# 在原完整 key 前加隔离前缀，不覆盖生产 key
./tamabox restore-images --input /var/backups/tamabox --yes \
--target-prefix tamabox-backup-test/manual-restore/
```
`--input` 可指向备份目录，也可直接指向 `images-manifest.json`。恢复会在任何远端操作前校验全部
manifest 条目和本地文件（普通文件、非 symlink、大小、实际 SHA-256）。默认先 Head 目标；任一目标已存在
即失败且零 Put，只有 `--overwrite` 才允许替换。`--dry-run` 不写对象，实际写入必须 `--yes`。
`--target-prefix` 会加在 manifest 的完整 key 前；非空前缀末尾没有 `/` 时会自动补一个。
Put 保留内容、原 key 路径（额外添加指定前缀）、`ContentType` 与 `CacheControl`，并使用单对象超时和有限重试。
**恢复不是事务**：中途失败会明确报告已成功数量，已上传对象不会自动回滚。
---
## 9. 典型处置流程
1. **发现**：收到告警邮件（同一箱主 24h ≥ 8 条 或 7d ≥ 20 条）→ 或箱主后台出现「被举报 N 次」。
2. **取证**：`reports --domain <domain>` 看条目、占比、历史处置。
3. **冷静期**：举报后 24 小时内不作判定（避免被集中举报推着走，也避免情绪化处置）。
4. **止血**：`restrict --level L1 --days 7 --reason "..."`。默认会通知箱主；
若判断通知会导致其转移阵地、需要先静默收口，加 `--no-notify`。
5. **清存量**：`hide-public --domain <domain> --only-reported`。
6. **观察**：7 天内复发 → 升 L2/L3；双方互挂 → **两边同级别处理，不选边**。
7. **收尾**：到期自动解除（不发信）；需要提前解封用 `unrestrict`（会给箱主发「已解除」通知）。
8. **留痕**：`reports --domain <domain>` 的历史处置段落就是处置记录（谁、何时、级别、原因）。
判定「挂人」的三要件（同时成立才处理）：
- **可识别性**：能让圈内人定位到具体账号/作品/主页（昵称、代称、@、外链、作品标签）
- **贬损或号召规避**：带「避雷/挂/别信/辱骂」这类定性，而不是中性描述
- **无公共利益**：纯私人纠纷、粉籍立场之争
只成立一两条 → 不处理或仅提示。
---
## 10. 排错
| 现象 | 原因 | 处理 |
|---|---|---|
| `No help topic for 'xxx'` | 构建入口不同步（根 `tamabox.go` vs `cmd/tamabox.go`） | 两处都注册后重新编译 |
| `find user: record not found` | `--domain` 填了昵称/登录名 | domain 是 URL 里的那一段，`/_/{domain}` |
| 处置后页面无变化 | 二进制是旧的 / 服务没重启 | `--help` 看命令在不在；抓线上 HTML 比对标记 |
| 待处理列表是空的 | 举报已被箱主处理（自动 accepted）或超过 30 天 | 正常；必要时直接查库 |
| 告警邮件一直没收到 | `[security] security_alert_email` 为空（静默跳过，无日志） | 配好并**重启** |
| 举报数始终是 1 | `trust_proxy` 未按部署环境配置，全部识别为代理 IP | 见 §2.4 |
| 箱主说「我改了但没生效」 | 处置期内严格度被锁定 / L2 禁止设为公开 | 看后台条幅；`reports` 查当前处置 |
| `--days 超过 90 天` 被拒绝 | 防手误设计，需要 `--force` | 确认时长后重试，或改用常规天数 |
| 处置成功但箱主说没收到邮件 | SMTP 未配 / 发送失败 / 用了 `--no-notify` | 看终端 warn；`[mail]` 配好后可 `restrict` 重发（同级别重设会替换记录） |
| 蜜罐记录的 `ip` 是 `127.0.0.1` | `trust_proxy` 未配，源站把所有人看成同一个代理 IP | 配 `trust_proxy`；**此时一次封禁会封掉整站**（见 [honeypot.md](honeypot.md) 的「部署」一节） |
| 整站都返回 403 | 蜜罐把反代 IP 封了（上一条的后果） | 重启进程（封禁是内存态）或等 `honeypot_ban_minutes` 到期 |
| 换了二进制但行为没变 | 进程没重启，跑的还是旧映像 | `ps -eo lstart,cmd \| grep tamabox` 比对启动时间与文件 mtime |
| `strings 二进制 \| grep 中文` 恒为 0 | `strings` 只输出可打印 ASCII，中文 UTF-8 被丢弃 | 用 `grep -ac "中文字符串" 二进制` |
| `honeypot` 命令不存在 | 二进制旧 / 两个构建入口未同步 | 重新编译后**重启进程** |
改完配置**必须重启**才生效（配置只在启动时读取一次）。
---
## 11. 明确不做的事
- **不做自动处置**：举报数达标只发邮件，不自动封禁。这个场景里举报本身就是攻击武器。
- **不做申诉后台**：申诉走邮件，处置结果由 CLI 写入。
- **不用配置文件当黑名单**：无法表达「N 天后自动解除」，最终会变成手工维护灾难。
- **不要在 CLI 之外直接改库**：`user_restrictions` 的写入必须带 `revoked_at` 语义，
手工 UPDATE 容易留下多条同时生效的记录（读取端会取最高级别，但不便于审计）。
docs/honeypot.md
-301
View File
@@ -1,301 +0,0 @@
# 蜜罐（虚假后台登录页）
给扫描器一组假的后台登录页（WordPress / phpMyAdmin / Jenkins / Tomcat / Grafana …）：它探后台路径时返回对应产品外观的假页面，它提交账号密码时把凭据记下来、并把它临时封掉。
一句话取舍：**这套功能的价值是「拿到对方正在用的字典」，不是「挡住扫描」。** 挡扫描靠 CDN 和 `autoban`；蜜罐只在「有人真的往假后台里填账号密码」时才有意义。
---
## 1. 生效范围
蜜罐挂在 `f.NotFound` 上 —— flamego 只有**路由表完全落空**时才会走到这里，所以：
- `/login`、`/register`、`/_/{domain}`、`/user/**`、`/api/v1/**` 这些真实路由永远不会被接管；
- 命中后短路返回，不查业务表、不渲染业务模板、不调用 `ctx.Next()`；
- 页面是纯静态 HTML，只含 canary 标记和假表单，不含任何真实信息。
匹配规则（`internal/security/honeypot/honeypot.go`）：
| 类型 | 例子 |
|---|---|
| 段前缀 | `/admin`、`/wp-admin`、`/.ssh`、`/.env`、`/phpmyadmin`、`/actuator` |
| 任意位置片段 | `/wp-includes/`、`/xmlrpc.php`、`/cgi-bin/`、`/.git/` |
| 文件后缀 | `*.zip`、`*.sql`、`*.bak`、`*.pem`、`*.key`、`*.env` |
| 自定义 | `[security] honeypot_paths`（逗号分隔，与内置清单取并集） |
业务路由前缀（`/login`、`/api`、`/static` 等）即使出现在自定义清单里也会被强制剔除，构成第二道保险。
改完路径后用 `tamabox honeypot paths` 看最终生效的完整清单（会按家族汇总条数）。
### 会伪装成哪几类后台
| 家族 | 典型路径 | 表单字段 / 响应 |
|---|---|---|
| WordPress | `/wp-login.php`、`/wp-admin`、`/wp-json` | `log` / `pwd`，带 `wordpress_test_cookie` |
| phpMyAdmin | `/phpmyadmin`、`/pma`、`/adminer.php` | `pma_username` / `pma_password` |
| Tomcat | `/manager/html`、`/host-manager` | **401 + `WWW-Authenticate`**（Basic，凭据从 `Authorization` 头取） |
| Jenkins | `/jenkins`、`/jnlpJars` | `j_username` / `j_password`，带 `X-Jenkins` 头 |
| Grafana | `/grafana` | `user` / `password`（深色主题） |
| GitLab | `/users/sign_in` | `user[login]` / `user[password]` |
| LuCI（路由器） | `/cgi-bin/luci`、`/luci` | `luci_username` / `luci_password` |
| Joomla | `/administrator` | `username` / `passwd` |
| 通用后台 | `/admin`、`/console`、`/zabbix`、`/jira` … | `username` / `password` |
**为什么要分类**：扫描器和爆破脚本都是「先按路径判断这是什么后台，再用它认识的字段名填表」。所有路径都回 WordPress 页面，等于在 `/phpmyadmin/index.php` 上告诉对方「这里不是 PMA」，对方直接换目标 —— 我们既拿不到凭据，也留不下有效取证。
**静态资源也一起伪装**：`/wp-admin/css/login.min.css`、`/wp-includes/js/*.js`、`/wp-admin/images/*.png` 这类请求回占位 CSS/JS/真 1×1 PNG。这些请求**不落库、不计数** —— 一次页面加载会打 5–10 个资源，逐个 INSERT 等于帮攻击者把写入放大十倍。插件目录下的 `.php` 则回 404（那是 webshell 探测，回登录页反而不像）。
**`/xmlrpc.php` 单独按 XML-RPC 回应**，不是登录页：
| 请求 | 响应 |
|---|---|
| `GET` / 其它非 POST | `405` + XML fault「XML-RPC services are disabled on this site.」 |
| `POST` 普通 `methodCall` | `200` + XML fault「Incorrect username or password.」 |
| `POST` `system.multicall` | 同上，但**一包里的所有凭据对都会被记下来** |
| `POST` `system.listMethods` | `200` + 方法列表（枚举类工具靠它确认对面是真 WP） |
为什么值得单独做：`system.multicall` 一次请求能塞进上千组用户名/密码，且绕开登录页的限速插件，是 WordPress 爆破里产出最高的一条通道。我们自己的 `X-Pingback` 响应头又正指着这个地址 —— 回 HTML 等于自己指路给对方看破绽。
动态值（phpMyAdmin 的 `token`、通用后台的 `csrf_token`、Jenkins 的 `X-Jenkins-Session`、GitLab 的 `_gitlab_session`）**每个请求都不同**。恒定值是最容易被指纹识别的特征：连打两次拿到一模一样的 token，任何脚本都能判定对面是伪造的。
单页渲染约 3.7 µs / 2 次分配、页面 1.5–2.5 KB，资源请求 0 分配（`BenchmarkRenderFamily` / `BenchmarkAssetFor` 守着）。
---
## 2. 配置
```ini
[security]
enable_honeypot = true
honeypot_paths =
honeypot_threshold = 1
honeypot_ban_minutes = 1440
honeypot_retain_days = 30
honeypot_auto_clean = true
honeypot_max_rows = 200000
honeypot_cred_dir = data/honeypot-creds
```
| 键 | 缺省 | 说明 |
|---|---|---|
| `enable_honeypot` | `false` | 总开关。关闭后 `/wp-admin` 等路径恢复原先的 302 → `/` |
| `honeypot_paths` | 空 | 追加诱饵路径，与内置清单取并集 |
| `honeypot_threshold` | `1` | **提交凭据**的封禁阈值（见 §3） |
| `honeypot_ban_minutes` | `1440` | 蜜罐封禁时长；显式 `0` 回退 `ban_duration_minutes` |
| `honeypot_retain_days` | `30` | 元数据与凭据文件的保留天数；`<= 0` 也回退 30 |
| `honeypot_auto_clean` | `true` | 每小时一轮后台清理；关闭后只能手动 `honeypot prune` |
| `honeypot_max_rows` | `200000` | 元数据行数上限（第二道闸）；显式 `0` = 不限 |
| `honeypot_cred_dir` | `data/honeypot-creds` | 凭据文件目录，进程工作目录为基准 |
> ⚠️ **配置项一律写成「注释独占一行 + 裸值」**。配置加载器开启了 `IgnoreInlineComment`，行尾 `; 注释` 会被并入值：`honeypot_max_rows = 200000 ; 说明` 解析出来是 `"200000 ; 说明"`，int 解析失败而 `MapTo` 不报错 —— 该项静默回退零值，日志里只会说「配置值不对」。
改完配置**必须重启**（配置只在启动时读一次）。
---
## 3. 两条封禁路径（最容易误解的地方）
| 行为 | 走哪条通道 | 阈值 | 是否立即封 |
|---|---|---|---|
| `GET /wp-login.php` 看一眼假页面 | 常规 `autoban.Record` | `ban_threshold_sensitive`（默认 10 次 / 60 秒） | 否 |
| `GET /wp-admin/css/login.min.css` 等资源 | **不计数、不落库** | — | 否 |
| `POST` 带该家族的凭据字段（`log`/`pwd`、`pma_*`、`j_*`、`user[login]` …） | 蜜罐 `autoban.RecordHoneypot` | `honeypot_threshold`（默认 1） | 是，立即封 |
| `POST /xmlrpc.php` 带 `methodCall`（含 `system.multicall`） | 蜜罐 `autoban.RecordHoneypot` | 同上 | 是，立即封 |
| `GET /xmlrpc.php` / `POST system.listMethods` | 常规通道 | 同上 | 否 |
| `POST` 不带任何凭据字段 | 常规通道 | 同上 | 否 |
**为什么 GET 不立即封**：爆破脚本的标准流程是「先 GET 探表单 → 再 POST 提交」。如果 GET 就吃 403，假登录页只被看了一次，对方根本没机会填表，凭据永远拿不到 —— 而这个功能的全部价值就在那份凭据上。
蜜罐通道**不受 `enable_auto_ban` 约束**：关掉常规自动封禁（它对共享出口误伤多）不会连带让蜜罐变成只记录不封禁的旁观者。
纯探测也不会被刷爆：元数据落库按「每 IP 每分钟一条」采样，凭据则是「有就存」——那才是要保的东西。
### 被封之后会看到什么
状态码永远 `403`，body 由 `[security] ban_image_path` 决定：
```ini
[security]
ban_image_path = data/403.webp
```
| 情况 | 响应体 |
|---|---|
| 配了合法图片 | 图片本身（`Content-Type` 按内容嗅探，png/jpeg/gif/webp 都行） |
| 留空 | 纯文字 `403 Forbidden`（改造前的老行为） |
| 文件读不到 / 是目录 / 不是图片 / 超过 2 MB | 纯文字 `403 Forbidden` + 启动日志 Warn |
```
$ curl -si https://你的站点/anything | head -5
HTTP/2 403
content-type: image/webp
content-length: 8608
cache-control: no-store, no-cache, must-revalidate
```
为什么要能换成图：爆破脚本常靠读响应体里的 `403 Forbidden` 确认自己已被拦，换掉 body 让这类判断失效；人肉访问（尤其是被共享出口连累的误封）时，看到一张明确的图比白屏好判断。但这是**可选**的——配错了不会影响封禁本身，只是回到纯文字。
几个约束，都是刻意的：
- **只认内容，不认扩展名**（`http.DetectContentType`）。把 `ban_image_path` 配成 `app.ini` / `.env` 会被拒绝并告警——否则等于把配置文件原样吐给每一个被封的攻击者。
- **上限 2 MB**。被封来源会反复重试，每张图都照常占用出网带宽；建议 256×256、20 KB 以内。
- **启动时读一次**，之后每个请求只读内存，不在热路径上做磁盘 IO。换图 = 换文件 + 重启进程。
- `no-store`：中间层缓存一张 403 没有意义，还会让解封后的响应继续命中缓存。
### 封的是一把「键」，不是一个人
`autoban` 的表就是内存里的 `map[键]到期时间`，键由 `shared.LimitKey` 生成：
- IPv4 → 原样（`203.0.113.7`）
- IPv6 → 折叠到 `/64`（`2408:8207:1234:5678::/64`），防止在单个 /64 内轮换地址绕过阈值
所以告警邮件里**可能有两个地址**：
| 字段 | 含义 |
|---|---|
| 来源 IP | 精确客户端地址，取证与对账用 |
| 封禁范围 | 实际写进封禁表的键；IPv6 下是 /64 前缀，整段一起封（IPv4 下与来源 IP 相同，不重复显示） |
两个直接后果，排障时先记住：
1. **封禁只在内存里** —— 重启进程即解除，邮件不会撤回；
2. **封的键与请求算出来的键必须一致** —— 换地址族（IPv6 访问 / IPv4 回源）或换 /64 前缀就不会被拦。
每次建封都会打一条 WARN，键、原因、时长、到期时间都在里面：
```bash
journalctl -u tamabox -n 50 | grep "已自动封禁来源"
# ban_key=2408:8207:1234:5678::/64 reason=蜜罐提交凭据 duration=24h0m0s expires_at=...
```
`ban_key` 就是被封的键，与邮件里的「封禁范围」一致。若这里没有记录，说明当时根本没建封（邮件可能是别的通道发的）；若有记录但仍能访问，就去比对请求算出来的键。
---
## 4. 凭据存在哪里
**用户名/密码不进数据库**，只追加到按天分文件的 JSONL：
```
data/honeypot-creds/creds-2026-10-21.jsonl
```
```json
{"time":"2026-10-21T16:13:50+08:00","ip":"117.x.x.226","method":"POST",
"path":"/wp-login.php","username":"admin2","password":"test456",
"fields":{"log":"admin2","pwd":"test456"},"raw_body":"log=admin2&pwd=test456",
"user_agent":"curl/8.22.0","banned":true}
```
| 项 | 值 |
|---|---|
| 目录权限 | `0700`（启动时强制 `chmod`） |
| 文件权限 | `0600` |
| 切分 | 按记录时间，一天一个文件 |
| 坏行 | 跳过（进程被杀留下的半条 JSON 不会让整天数据报废） |
| 清理 | 与 `honeypot_retain_days` 同步，只删「整天都过期」的文件 |
**为什么不入库**：明文账号密码一旦入库，就会跟着进备份、主从复制、以及任何有库只读权限的报表/BI 工具，事后无法彻底清除。文件可以单独挂卷、单独设权限、到期直接删。
数据库里只保留「发生过一次带凭据的提交」这个事实（`honeypot_hits.had_fields`），以及 IP / 路径 / UA / 是否封禁这些元数据。
> `ip` 两处存的都是**精确客户端地址**（IPv6 保留完整地址），不是封禁用的 `/64` 聚合键 ——
> 取证要能定位到具体主机。想知道「封了多大范围」，看告警邮件的「封禁范围」或日志里的 `ban_key`。
> ⚠️ 这些是**外部攻击者提交的真实账号密码**，很可能是从别处泄露后复用的。请按敏感数据对待：不要提交进版本库（`/data/` 已在 `.gitignore`）、不要参与备份、不要贴到公开群组。
---
## 5. 部署：反向代理必须配 `trust_proxy`
这是**部署时最容易踩、后果最严重**的一条。
如果站点在 nginx / Cloudflare 之后而 `trust_proxy = false`：
- 源站看到的所有请求都来自代理地址（常见 `127.0.0.1`），**取证数据失去意义**；
- 更糟：一次蜜罐命中封的是 `127.0.0.1`，而所有访客在源站眼里都是这个 IP —— **等于封掉整站**。
正确配置：
```ini
[security]
trust_proxy = true
trusted_proxies = 127.0.0.1
```
> ⚠️ 前提：**源站不能直接被公网访问**（Cloudflare Tunnel / Authenticated Origin Pull / 防火墙只放行回源网段）。`trust_proxy = true` 时程序会信任 `CF-Connecting-IP` 这类权威头，源站若可直连，攻击者能伪造它来绕过封禁、或反手封掉别人。
程序在「命中回环地址且 `trust_proxy` 未开」时会打一条一次性 WARN（24 小时冷却）提醒检查这里。
验证：触发一次蜜罐后看凭据文件里的 `ip` 是不是真实客户端地址。
---
## 6. 升级：清掉历史明文列
早期版本把 `username` / `password` / `fields` / `raw_body` 直接存在 `honeypot_hits` 上。结构体已经删掉这些字段，但 **GORM 的 AutoMigrate 不会删既有列** —— 老库升级上来后，历史明文还在表里。
启动时会打一条 WARN：
```
honeypot_hits 上仍残留旧版明文凭据列，请执行 TamaBox honeypot purge-creds 清除
```
清理（**不可逆**，先备份）：
```bash
pg_dump -Fc <dbname> > before-purge-$(date +%F-%H%M).dump
./tamabox honeypot purge-creds # 列出四列，输入 yes 才执行
```
只处理当前库；**历史备份与从库里可能仍有明文**，需要自行处理。
---
## 7. 日常运维
```bash
./tamabox honeypot hits # 最近 24h 的凭据（密码默认脱敏）
./tamabox honeypot hits --ip 1.2.3.4 --show-password
./tamabox honeypot stats --days 7 # 来源排行（IPv6 按 /64 聚合）+ 路径排行 + 凭据排行
./tamabox honeypot paths # 当前生效的诱饵路径
./tamabox honeypot size # 表行数 + 磁盘占用 + 凭据文件体积
./tamabox honeypot prune --days 30 # 手动按保留期清（元数据 + 凭据文件）
```
`hits` / `paths` 不连数据库（DB 挂了也能查）。
---
## 8. 排障
| 现象 | 原因 | 处理 |
|---|---|---|
| **邮件说封了，但还能正常访问** | ① 进程重启过（封禁是内存态）② 后续请求换了地址族 / 换了 /64 前缀 ③ `trust_proxy` 未配，封的是反代地址 | 看日志里 `已自动封禁来源` 的 `ban_key`，与 `honeypot hits` 里的 IP、以及本机 `curl -6 ifconfig.co` 比对；见 §3「封的是一把键」 |
| `/wp-admin` 还是 302 | `enable_honeypot` 未开 / 配置未重启生效 | 看启动日志；`honeypot paths` 确认开关状态 |
| 记录里 `ip` 是 `127.0.0.1` | `trust_proxy` 未配 | 见 §5；**注意此时封禁会封全站** |
| 整站都返回 403 | 蜜罐把反代 IP 封了（上一条的后果） | 重启进程（封禁是内存态）或等 `honeypot_ban_minutes` 到期 |
| GET 假页面不封禁 | 设计如此 | 提交凭据才立即封，见 §3 |
| 记录里 `path` 带前导空白/奇怪字符 | 上游（nginx/CF）改写了 URI | 代码已清洗并打 WARN；根因建议查 `proxy_pass` / `rewrite` |
| `honeypot` 命令不存在 | 二进制旧 / 两个构建入口未同步 | `go build -o tamabox .` 后**重启进程** |
| 改了代码但行为没变 | 只替换了二进制，进程还在跑旧映像 | `kill` 旧进程后按原方式重新拉起 |
| 凭据文件没有生成 | `honeypot_cred_dir` 不可写 | 看启动日志里的「凭据目录不可用」告警 |
| 启动报 `honeypot_hits 上仍残留…` | 老库有历史凭据列 | `honeypot purge-creds`（§6） |
排障时两个容易误判的点：
- **验证二进制里有没有某个中文字符串，不能用 `strings`** —— 它默认只输出可打印 ASCII，UTF-8 中文整段被丢弃，`strings x | grep 中文` 恒为 0。用 `grep -ac "中文字符串" x`。
- **替换二进制 ≠ 生效**，进程必须重启；前台跑 `./tamabox web` 若立刻返回，通常是端口被旧进程占着。
- **邮件里的「来源 IP」不是封禁键**：IPv6 下前者是精确地址、后者是 /64 前缀，拿前者去查后者永远对不上。判「封没封」只看 `ban_key`。
---
## 9. 设计取舍（已知限制）
- **GET 探测不封**：见 §3。代价是扫描器可以反复拿假页面，收益是能拿到凭据。
- **假页面带 canary**：只放在 HTML 注释里（`<!-- build: tb-hp-... -->`），用于确认「这确实是蜜罐返回的页面」；`<meta name="generator">` 伪装成 `WordPress 6.4.3`，不主动暴露技术栈。
- **只挡 NotFound**：如果将来给 `/admin` 之类路径注册了真实路由，蜜罐会自动让位 —— 这是刻意设计（业务优先）。
- **告警邮件仍带明文用户名/密码**：这正是它的价值（看到对方在用什么字典），但也意味着邮件是敏感物，收件人只应是你自己。
- **不主动反制**：不回打、不上报第三方、不做删除/篡改，只有「记录 + 临时封禁」。
- **XML-RPC 的凭据提取是启发式的**：不上 `encoding/xml` 解析（蜜罐会被高频命中），而是抓出所有 `<string>`、剔除方法名与站点 URL 后两两配对。`wp.getUsersBlogs` 的第一个参数是 `blog_id`，若是数字会让配对错位一位——为此会把原始串全量写进取证文件的 `fields`（`xmlrpc.0`、`xmlrpc.1` …），即便配对失败原文也不丢。
- **`X-Pingback` 需要配 `external_url`**：没配就不发这个头（相对路径比不发更假）。
docs/theme-assets-cdn.md
-135
View File
@@ -1,135 +0,0 @@
# 把主题素材放到对象存储（任意 S3 兼容）
这里的「对象存储」不特指某一家：Cloudflare R2、自建 MinIO、Backblaze B2、
阿里云 OSS 的 S3 兼容端点、腾讯云 COS 的 S3 兼容端点都走同一套 SigV4，
差别只在 Endpoint、Region、是否路径风格。**放本地还是放对象存储，由部署者自己决定** ——
主题生成器里「素材托管」就是这两选一。
现状：主题素材在 `static/images/themes/<slug>/`，通过 `static/fs.go` 的 `//go:embed images/themes`
随二进制发布。好处是部署即生效、不依赖外部服务；代价是**换一张图就要重新编译部署**，
而且一张 1920×1080 的场景图会让二进制大几百 KB。
主题素材只有一处引用：**主题 CSS 里的 `url(...)`**（`--tb-page-image` / `--tb-page-pattern` /
`--tb-deco`）。分享卡是 Go 里用 `imaging` 画出来的，不读主题素材。所以只要解决「CSS 里的地址指向哪」，
就把整套素材搬走了。
下面三种做法按「改动量从 0 到有代码」排列，选一个即可，不必叠加。
---
## A. 生成器直接写绝对地址 + 就近上传（已支持，推荐）
`dev/theme-builder` 左侧「**素材托管**」有两个选项：本地（随二进制）/ S3 兼容存储。
选 S3 后填：
```
Endpoint https://<账号>.r2.cloudflarestorage.com ← MinIO / B2 / OSS / COS 填各自的
Region auto ← R2 用 auto；MinIO 常为 us-east-1
桶名 my-theme-assets
路径前缀 themes
公开前缀 https://cdn.example.com/themes ← 留空 = 按 Endpoint 推导
Access Key / Secret Key
```
然后：
1. **测试连接** —— `HEAD` 桶（连通+凭据）→ `PUT` 探针（写权限）→ `GET` 读回（内容一致）
→ 匿名 `GET`（能不能被浏览器直接读到）→ 删除探针。失败会把 S3 的 `<Code>` 翻成人话。
2. **上传素材** —— 逐张 PUT 本次主题引用到的图，键为 `<路径前缀>/<slug>/<id>.webp`，
带 `public, max-age=31536000, immutable`。成功后自动把导出用的「素材前缀」填好。
3. **检测远端** —— `ListObjectsV2` 列出 `<前缀>/<slug>/` 下所有对象，按对象键名跟本地比：
一致 / 旧图（同名但大小不同）/ 多余（当前主题已不引用）/ 缺失。
可以「补齐差异」（只传缺的与旧图）、「删除多余」，也可以单行覆盖或删除。
上传经本机 `serve.py` 代理（`/api/s3/test`、`/api/s3/upload`），浏览器不直连对象存储：
**不需要给桶配 CORS**，密钥只在当前标签页的 sessionStorage 与内存里，
不进草稿、不进工程 json、不进导出 zip。
不想用面板也行，导出的 zip 里图片照旧在 `static/images/themes/<slug>/*.webp`，
用任何 S3 客户端推上去即可：
```bash
aws s3 sync static/images/themes/shiroko/ s3://my-bucket/themes/shiroko/ \
--endpoint-url https://<你的 Endpoint> --cache-control "public, max-age=31536000, immutable"
sed -i 's#/static/images/themes/shiroko/#https://cdn.example.com/themes/shiroko/#g' \
static/css/themes/shiroko.css # 已有主题不想重导时，等价于「填前缀再导一次」
```
- 优点：零服务端改动、零跳转、缓存最优（CDN 直接命中）；
- 缺点：域名烘焙进 CSS —— 换域名/换路径要**重新导出**（旧主题可以用 `sed` 批量替换）；
- 仓库里可以删掉 `static/images/themes/<slug>/` 来缩小编译产物，**确认 CSS 已是绝对地址**再删。
---
## B. 应用内 301 跳转（配置驱动，CSS 一行都不用改）
`conf/app.ini`：
```ini
[theme]
asset_base = https://cdn.example.com/themes ; 留空 = 本地静态目录
```
中间件必须在 `flamego.Static` **之前**注册（`internal/route/route.go` 里 `f.Use(flamego.Static(...))` 前面）：
```go
// 主题素材转发到对象存储：命中前缀就 301 出去，其余请求原样放过。
// 必须挂在 static 中间件之前——Static 命中本地文件就直接返回了，轮不到这里。
func themeAssetRedirect() flamego.Handler {
const prefix = "/static/images/themes/"
return func(ctx flamego.Context) {
base := theme.AssetBase() // 从 conf 读，空串 = 不接管
p := ctx.Request().URL.Path
if base == "" || !strings.HasPrefix(p, prefix) {
return
}
w := ctx.ResponseWriter()
w.Header().Set("Cache-Control", "public, max-age=86400")
http.Redirect(w, ctx.Request(), base+strings.TrimPrefix(p, prefix), http.StatusMovedPermanently)
}
}
```
- 优点：已有主题、生成器导出的相对地址**都能用**，切 CDN 只改配置；
- 缺点：冷缓存时每张图多一跳；**301 会被浏览器长期缓存**，以后想切回本地，
老访客可能还在访问 CDN（介意的话用 `302`，或一开始就用方案 A）；
- 本地开发记得把 `asset_base` 留空，否则断网时素材全 404。
---
## C. 边缘 / 反代改写（零代码）
素材路径有稳定前缀，最适合在边缘处理：
- **Cloudflare**：Origin Rule / Transform Rule，把 `/static/images/themes/*` 的 Host 改成
R2 自定义域（如 `cdn.example.com`），或 Redirect Rule 直接 301 过去；
- **nginx**：`location /static/images/themes/ { proxy_pass https://cdn.example.com/themes/; }`，
或 `rewrite` 成 CDN 地址后 `return 301`。
- 优点：应用完全不知道素材在哪，不占应用带宽；
- 缺点：绑定部署环境，本地跑没有等效层（要考虑 fallback）。
---
## 三种方案共同要处理的细节
1. **缓存**：对象存储上建议
`Cache-Control: public, max-age=31536000, immutable`（文件名带版本时）。
换图**不要覆盖同名对象**——要么换 `id`（生成器里改文件名），要么给 URL 加 `?v=`；
Cloudflare 默认把 query string 计入缓存键，所以 `?v=` 是有效的。
2. **CORS 不用配**：`background-image` 不触发 CORS，匿名 GET 即可。
3. **主题 CSS 本身不用上 CDN**：一个主题只有几 KB，而且随 `StaticVersion` 走缓存键，
留在 `static/css/themes/` 更省事。
4. **深色模式没有素材**（深色块 `--tb-deco` 恒为 `none`），别只传浅色图就以为漏传了。
5. **分享卡不受影响**：`route/question/share.go` 用 `imaging` 直接画，不加载主题图片。
6. 迁完之后 `go build` 会小一圈，但**主题 css 仍是编译期 embed**：改 CSS 还是要重编译部署。
---
## 建议
- 只是想让部署产物变小、换图不用重编译 → **A**（生成器里配好 S3、测通、一键上传，最省事，缓存也最好）。
- 想保留「素材可以随时换、CSS 不用重发」的灵活性 → **B**（配一个 `asset_base`，接受多一跳）。
- 站点已经在 Cloudflare 上、且愿意在边缘配规则 → **C**（最干净，但迁移成本在运维侧）。
- 就用本地目录、不想依赖任何外部服务 → **什么都不用做**（默认行为，素材随二进制发布）。
docs/theme-new-sakura.md
-204
View File
@@ -1,204 +0,0 @@
# new-sakura（新·樱花）：纯 CSS 樱花主题
和已有的 `sakura` 的区别：`sakura` 是「粉底 + 网点」的静态配色；`new-sakura` 把樱花本身
做成了**可摆放的装饰层** —— 整朵花、带缺口的花瓣、带枝的花朵树，全部是内联 SVG 的
`data:image/svg+xml` URI，写在主题 CSS 里。
因此这个主题：
- **不需要任何图片素材**，也不依赖对象存储（`static/images/themes/new-sakura/` 是空的）；
- 任意视口缩放都不糊（矢量），DPI 无关；
- 换花色只改 `dev/theme-tools/gen_new_sakura.py` 里的一个色值，重跑即得；
- 没有额外 HTTP 请求 —— SVG 就在 CSS 里。
代价是 CSS 有 54KB（服务端有 gzip，实际传输约 4KB）。主题 CSS 走 `StaticVersion` 缓存，一次性开销。
## 结构
```
static/css/themes/new-sakura.css ← 生成产物，别手改
dev/theme-tools/gen_new_sakura.py ← 改这里，重跑
```
```bash
python dev/theme-tools/gen_new_sakura.py
```
生成器脚本里有三样东西：花形（`blossom` / `petal` / `branch` / `pattern`）、
每个页面作用域的位置表（`SCOPES`）、以及配色（`LIGHT` / `DARK`）。
## 每个页面的樱花位置
`--tb-deco` / `--tb-deco-size` / `--tb-deco-position` 三组各 10 槽，必须等长
（`TestDecoSlotCount` 会逐文件逐声明检查）。
| 作用域 | 选择器 | 构图 |
| --- | --- | --- |
| global | `html[data-theme-style="new-sakura"]` | 右下花枝 + 左上大花 + 两片落瓣 |
| box | `…[data-page-scope="box"]` | 右上花枝垂下（细端在外、粗端朝内）+ 左下花与落瓣 |
| question | `…[data-page-scope="question"]` | 左下花枝斜穿 + 右上大花 + 落瓣 |
| admin | `…[data-page-scope="admin"]` | 左上花枝 + 左侧底部小花（卡片占满宽度，右侧会被盖住） |
| profile | `…[data-page-scope="profile"]` | 右下花枝 + 左侧竖排小花与落瓣 |
| vote | `…[data-page-scope="vote"]` | 左上花枝 + 右侧花与落瓣 |
位置一律「关键字 + 偏移」两值写法（`right -24px top -16px`）。三值语法里混用
`left` / `bottom` 关键字是非法的，整条声明会作废、花瓣静默回到左上角。
### 窄屏（≤640px）
装饰层全部置 `none`：卡片占满宽度，左右只剩 ~16px 边距，枝条放哪儿都会糊在字上。
樱花改由底纹承担 —— `@media` 里换成**加强版 pattern**（透明度 ×1.9）并把格子收到 180px；
桌面那套 0.18~0.34 的透明度在 390px 上实测接近一片纯粉。
试过在「顶栏与卡片之间」那条 35px 的带子里放两朵小樱花：box 页卡片从 y=122 起还行，
question / admin 页卡片从 y=110 起就切掉半个，结果是黏在卡片边上的粉色碎块。手机上没有
可靠的留白，就不放装饰层 —— 观感交给配色与底纹。
⚠️ **窄屏覆盖必须重新声明每个作用域选择器**：`@media` 不提升特异性。
作用域块是 `html[data-theme-style][data-page-scope="box"]`（0,2,1），而媒体查询里常见的
`html[data-theme-style]`（0,1,1）根本压不住它 —— 表现是「手机上装饰层没关掉，桌面版照样铺开」。
深色作用域块更是 0,3,1，还得再补一条 `[data-theme="dark"][data-theme-style][data-page-scope]`。
`TestNarrowMediaOverridesScopedDeco` 会在这里把关：外层每一处非 none 的 `--tb-deco`，
媒体查询里都要求有同属性名、属性数不少于它的选择器再声明一次。
### 深色
- 花瓣换成更亮一档的粉（`#f0a0b8`），枝条提亮到能看见；
- 底纹 `--tb-page-pattern: none`：浅粉花瓣压在深底上会变成一层噪点；
- 整页背景改深色渐变（不用纯色，避免大面积死黑）。
深色块必须写成 `html[data-theme="dark"][data-theme-style="new-sakura"]`（三重选择器），
只写浅色块会被同特异性的作用域块盖掉。
## 顶栏与手机底栏
顶栏走**磨砂玻璃**，不是实色也不是全透明：
```css
--tb-navbar: rgba(253, 246, 248, 0.72); /* 亮色；深色 rgba(34, 26, 30, 0.72) */
html[data-theme-style="new-sakura"] .uk-navbar-container:not(.uk-navbar-transparent) {
-webkit-backdrop-filter: blur(12px);
backdrop-filter: blur(12px);
}
```
三种写法的实测结论：
| 写法 | 现象 |
| --- | --- |
| 实色 `#fdf6f8` | 花枝经过顶栏时被齐刷刷切掉一段，像被裁过 |
| `transparent` | 花枝完整了，但顶栏"消失"：导航没有依托，文字直接压在花纹上 |
| `rgba(...,0.72)` + `blur(12px)` | 花枝透过来但被模糊成柔光，顶栏仍是一块可辨认的面 |
0.72 是怎么定的：导航文字 `#6d555d` 压在顶栏上，纯底色 6.34:1；最坏情况（深花瓣正好在顶栏后面）
压平后 5.08:1，仍过 AA。再往下调透明度就会掉到 4.5 以下。
`TestNavbarNotFullyTransparent` 会拦住 `--tb-navbar: transparent`（以及 `rgba(...,0)`、
`#rrggbb00`）—— 这条不是审美偏好，是把上面第二种写法踩过之后立的规矩。
手机底栏（`#tb-mobile-utils`）在 `base.css` 里写死 `rgba(255,255,255,.92)`，压在粉底上是
一条白杠；主题里按同一思路改成 `rgba(253,246,248,.92)` / `rgba(34,26,30,.92)`。
另外 box 作用域的花枝从 `top -16px` 下移到 `top 26px`：顶栏半透明后，700~760px 宽度下
枝头正好压在「登录」上（实测截图确认）。顶栏高 60 + 外边距 20，26px 起笔即落在顶栏下沿之上，
宽屏仍是"从右上角长出来"的观感。
## 配色与对比度
| 令牌 | 亮色 | 深色 | 说明 |
| --- | --- | --- | --- |
| `--tb-bg` | `#fdf6f8` | `#221a1e` | 纯色，不用渐变（整页色感一致） |
| `--tb-surface` | `#ffffff` | `#2c2227` | 卡片 |
| `--tb-text` | `#3a2c31` (12.4:1) | `#f3e6ea` (14.0:1) | |
| `--tb-text-secondary` | `#6d555d` (6.3:1) | `#c9aeb8` (8.3:1) | |
| `--tb-text-muted` | `#77626a` (5.3:1) | `#ab9099` (5.8:1) | 踩 AA 下限 |
| `--tb-primary` | `#b8436a` (4.9:1) | `#ff93b4` (8.2:1) | 原候选 `#c14a72` 只有 4.39:1，压深 |
| `--tb-on-primary` | `#ffffff` (5.2:1) | `#1b1014` (8.9:1) | 主色按钮上的字 |
## 素材包（可选，已传到对象存储）
主题线上**不需要**任何素材：樱花是内联矢量。但同一个花形也导出成了位图，
放在对象存储上备用（`themes/new-sakura/`，共 7 个对象）：
| 键 | 内容 |
| --- | --- |
| `new-sakura.css` | 主题本体（备份，便于分发） |
| `branch-right.webp` / `branch-left.webp` | 花枝 840×640 透明底（互为镜像） |
| `blossom.webp` | 单朵樱花 400×400 透明底 |
| `petal.webp` | 带缺口的花瓣 240×336 透明底 |
| `pattern.webp` | 平铺底纹 600×600 透明底 |
| `INSTALL.txt` | 包内说明 |
重新导出 / 上传（`--upload` 会一起传 CSS、位图和生成的 `INSTALL.txt`）：
```bash
python dev/theme-tools/export_assets.py # 只导出到 outputs/sakura-assets
python dev/theme-tools/export_assets.py --upload # 导出并上传，读 data/r2.txt
```
`data/r2.txt` 是部署凭据（`image_endpoint` / `image_access_id` / `image_access_secret` /
`image_bucket` / `image_bucket_cdn_host`），**不进版本库**（`.gitignore` 里的 `/data/`）。
`image_bucket_cdn_host` 与 `conf/app.ini` 同名同义：只写主机名，不带 `https://` 和路径；
没有它时 `INSTALL.txt` 里的公开地址会写成占位符。
缓存策略：位图 `max-age=86400`、CSS 镜像 `300`、`INSTALL.txt` `60`。
这些键**都不带内容版本**，所以刻意不用 `immutable` —— 否则重新导出后，浏览器与 CDN
一年内拿到的都还是旧图。想要一年长缓存，得把内容哈希写进文件名（CSS 里的地址跟着换）。
⚠️ 若某个键曾经以 `immutable` 传过（本主题第一版就是这样），CDN 会一直给旧副本，
改完必须去控制台按 URL 清一次缓存，光重传没用。
### 位图版（引用对象存储）
桶绑了自定义域 `r2.337845818.best`（实测匿名 GET 200、`image/webp`、大小一致），
所以可以把 CSS 从内联切到位图：
```bash
python dev/theme-tools/gen_new_sakura.py \
--asset-base https://r2.337845818.best/themes/new-sakura \
--out static/css/themes/new-sakura.css
```
| 版本 | CSS | gzip 后 | 额外请求 | 清晰度 |
| --- | --- | --- | --- | --- |
| 内联 SVG（默认） | 53.8KB | **4.0KB** | 0 | 矢量，任意 DPR |
| 位图 | 11.8KB | 2.8KB | 5 个 webp，共 48.9KB | 2 倍图 |
服务端挂了 gzip（`internal/route/gzip.go`），所以内联版**总传输 4.0KB**，比位图版的
2.8 + 48.9 = 51.7KB 小一个数量级 —— 换位图省不了流量，只是把开销从 CSS 挪到图片。
位图版唯一正当的理由是**素材要单独复用**（分享卡、海报、其它系统）。
⚠️ 直接连桶的 S3 endpoint（`*.r2.cloudflarestorage.com`）会 403，**只有自定义域/r2.dev 可匿名读**。
切之前先 `curl -I` 验一下前缀；切完 `go build` 部署，否则 embed 里还是旧的。
## 为什么不用主题生成器出图
生成器的装饰层只支持「图片素材」（导出时打进 zip 或传对象存储），没有内联 SVG 图层。
要把樱花做成可摆放的图层，只能在设计上二选一：
1. 生成图片素材（花瓣 PNG/WebP）→ 可以用生成器、可以放 S3，但会有位图缩放、额外请求；
2. 内联 SVG 写进 CSS → 零素材、任意缩放不糊，但生成器管不到。
`new-sakura` 选 2，因为「用 CSS 做樱花」本身就是这个主题的诉求。
生成器仍然可以用来**预览**它：`?demo=1&fresh=1` 起画板，把 `new-sakura.css` 注入即可。
## 怎么验证
```bash
go test ./internal/theme # 10 槽等长、深浅块成对、必需令牌齐全、窄屏覆盖特异性
```
视觉自检用项目真实页面快照：
```bash
TEST_PREVIEW=1 go test ./templates -run TestGenPreview
python dev/theme-builder/serve.py
# 打开 outputs/preview-box-light.html，DevTools 里给 <html> 加
# data-theme-style="new-sakura" data-page-scope="box"
```
## 上线
1. `conf/app.ini` 的 `[theme] available` 加上 `new-sakura`（不改就「设置页看不到」，现象和部署没生效一样）；
2. 重新 `go build` —— 主题 CSS 是编译期 embed，只重启不重编不会变；
3. 箱主设置页 → 账号 → 外观，选择「新·樱花」。
docs/theme-page-scope.md
-86
View File
@@ -1,86 +0,0 @@
# 主题的页面作用域（data-page-scope）
一套主题过去只能有一种装饰：人物永远站在左下角，不管当前是箱主页、单题页还是题目列表。
单题页正文长、题目列表信息密，同一套装饰在三种页面上要同时成立很难。
现在服务端会按请求路径给 `<html>` 打一个 `data-page-scope`，主题可以对每个页面分别配
整页背景与装饰层。
## 取值
| 值 | 路径 | 说明 |
| --- | --- | --- |
| （无属性） | — | 全局默认 |
| `box` | `/_/{domain}`、`/_/{domain}/tag/*` | 箱主页（问题列表） |
| `question` | `/_/{domain}/{qid}` | 单个问题 |
| `admin` | `/user/questions`、`/user/votes/*` | 题目 / 私聊管理列表 |
| `profile` | `/user`、`/user/profile` 等 | 设置页 |
| `vote` | `/vote/{token}` | 投票页（跟随发布者的主题） |
| `home` / `explore` | `/`、`/explore` | Go 侧会返回，但**这两页不加载主题 css** |
来源：`internal/context.pageScope()`，测试在 `internal/context/context_test.go` 的 `TestPageScope`。
## 选择器与特异性
```css
/* 全局 */
html[data-theme-style="SLUG"] { … }
/* 某一页覆盖 */
html[data-theme-style="SLUG"][data-page-scope="question"] { … }
```
特异性 0,2,1 与深色块 `html[data-theme="dark"][data-theme-style="SLUG"]` 相同，
而覆盖块写在文件后面，**会盖掉深色块**。所以深色必须再写一条三重选择器：
```css
html[data-theme="dark"][data-theme-style="SLUG"][data-page-scope="question"] { … }
```
不写的话，深色模式下会拿到浅色的覆盖块 —— 典型表现是「深色页面里突然出现一块白天场景」。
## 覆盖块写什么
通常只覆盖这三组：
```css
html[data-theme-style="SLUG"][data-page-scope="question"] {
--tb-page-image: none; /* 不放整页场景 */
--tb-page-pattern: none;
--tb-deco: …; /* 10 个值 */
--tb-deco-size: …; /* 10 个值 */
--tb-deco-position: …; /* 10 个值 */
}
```
配色（`--tb-bg` / `--tb-surface` / `--tb-text` / `--tb-primary`）一般不要按页面改：
同一个主题在不同页面换配色，用户会觉得走错站了。
## 10 个槽位
`--tb-deco` / `--tb-deco-size` / `--tb-deco-position` 三组必须**等长且写满 10 个**。
少一个不会报错，CSS 会按列表长度循环取值，于是图层与 size/position 整体错位：
- 整页重复同一张插画（第一次踩坑就是这个）
- 人物跑到页面左上角（`background-position` 整条声明非法时回落初始值）
`internal/theme/slots_test.go` 的 `TestDecoSlotCount` 会逐个文件、逐处声明检查，
包括 base.css 与所有主题 css（含作用域覆盖块）。写主题时不用记，跑测试就行。
`background-position` 一律写成两值 `calc()`：
```css
--tb-deco-position: calc(0% + 40px) calc(100% - 36px),
calc(50% + 0px) calc(50% + 0px), …;
```
- 百分比是相对 **(容器 − 图片)** 的剩余空间，不是相对容器
- `0%` 左/上、`50%` 居中、`100%` 右/下
- **不要**混用 `left` / `bottom` 关键字：「水平居中 + 垂直贴底」会变成三值语法，
一旦不合规范整条声明作废，图层静默掉到左上角
## 可视化编辑
手写这些值不现实，用 `dev/theme-builder/`（见同目录 README）：以真实页面为画布，
按页面切换、拖拽定位、导出 zip。它生成的 CSS 直接过 `TestThemeCSSComplete` 与
`TestDecoSlotCount`。
docs/theme-shiroko-assets-spec.md
-127
View File
@@ -1,127 +0,0 @@
# 主题素材规格（shiroko）
给外部生成工具用的参数表。照着填尺寸/比例/雾度，导出后按「换图清单」替换即可。
所有尺寸都按 **2× 出图、1× 显示** 写，避免高分屏发虚。
## 一、总表
| 文件 | 用途 | 画布（生成） | 画布（导出） | 显示尺寸 | 透明 | 体积上限 |
| --- | --- | --- | --- | --- | --- | --- |
| `chibi/window.webp` | 人物 | 270 × 920 | 135 × 460 | 高 400px（宽 ≈117） | ✅ 需要 | 40 KB |
| `props/bike.webp` | 自行车 + 步枪 | 794 × 518 | 397 × 259 | 高 259px（宽 ≈397） | ✅ 需要 | 40 KB |
| `scene-desktop.webp` | 教室背景（桌面） | 3840 × 2160 | 1920 × 1080 | `cover` 铺满 | ❌ 不需要 | 40 KB |
| `scene-mobile.webp` | 教室背景（≤900px） | 1440 × 2006 | 720 × 1003 | `cover` 铺满 | ❌ 不需要 | 30 KB |
| `pattern-dark.svg` | 深色模式平铺纹样 | 240 × 240 | 240 × 240 | 平铺 | ❌ | 2 KB |
比例（认准这个，比像素更重要）：
- 人物 **1 : 3.41**（宽 : 高 ≈ 0.293）
- 道具 **1.53 : 1**（397 : 259）
- 桌面背景 **16 : 9**
- 移动背景 **0.718 : 1**（≈ 9 : 12.5）
## 二、人物 `chibi/window.webp`
| 项 | 值 |
| --- | --- |
| 画布 | 270 × 920 px，透明背景 |
| 姿势 | 侧后方 3/4 视角、双手背在身后、头略向右（**不要正面直视**） |
| 脚底 | **贴画布底边**（误差 ±4px），不要留空白 |
| 头顶 | 贴画布上沿；若画光环，环心必须透明 |
| 左右余量 | 各留 10~20px，别让手臂被画布裁掉 |
| 雾度 | RGB 压白 **16%**：`v' = v×(1-0.16) + 255×0.16` |
| 色彩 | 下表是**压白 16% 之后**的显示值，生成时按 `原色 = (显示值 − 40.8) / 0.84` 反算 |
| 部位 | 显示值 | 生成时用 |
| --- | --- | --- |
| 头发 | `#c4c3c6` | `#b9b8bb` |
| 围巾 | `#8abbc6`（青绿，别用纯蓝） | `#8fc1c9` |
| 西装 / 上衣 | `#565e72` | `#3a4256` |
| 鞋 | `#4f4f4f` | `#3f3f3f` |
| 袜 | `#ffffff` | **用 `#ededed`**（纯白会和背景粘在一起，抠图会吃穿） |
| 光环 | `#8abbc6` 细环 | `#7fd3dc` |
要点：
- **不能有描边**。平涂色块、无 line art、无渐变。
- 抠图后检查三处必须透明：**手与背之间**、**两腿之间**、**光环环心**。
这三处是闭合区域，只从四角抹白是抹不掉的（我们踩过）。
- 白袜子是 `#ededed` 左右，背景是 `#fdfdfd`，两者只差 16 级——抠图时**不要把阈值开大**，否则袜子会被吃穿。
## 三、道具 `props/bike.webp`
| 项 | 值 |
| --- | --- |
| 画布 | 794 × 518 px，透明背景 |
| 内容 | 银色／白色城市自行车 + 一把细长步枪斜靠车架 |
| 朝向 | **车头朝右**（和人物同向） |
| 地面 | 轮子底线贴画布底部，下方留 12~16px 给接触阴影 |
| 阴影 | 可以在图内自带一层椭圆软影（不透明度 15~20%，模糊 8~12px） |
| 雾度 | RGB 压白 **26%**（比人物淡一档，它在人身后） |
| 背景 | **必须是纯色绿幕或透明**，不要白底（白色车架 + 白底 = 无法分离，见下方“白上白”） |
要点：
- 侧视图即可，但不要画成“图标”——轮辐、脚踏、链条这些细节保留，否则缩到 259px 会变成一个圈。
- 枪要细长、冷色（灰蓝），**不要木色**（会像双管猎枪）。
⚠️ **白上白（本项目踩过）**：白底 + 白车架时，车身涂装和背景是同一个白（实测都是 `#f9f9f9`，
差 0~3 级），颜色完全分不开；四角 floodfill 只能吃掉外圈，轮圈内、车架三角、车筐里的白会整块留下，
看上去就是「没抠干净」。此时的取舍只有两条：
1. 把这批白**全部**设为透明 —— 车身填色一起走，成品是**线稿风**（描边 + 粉色轮圈 + 蓝枪托仍在，
轮辐、车架、车筐网格都清楚，现有的 `bike.webp` 就是这么做出来的，不透明率 19.4%、剩余近白 0%）；
2. 重新出一张**绿幕/透明背景**的素材，车身用浅灰蓝等中间调（白车在浅色场景里本来就发飘）。
## 四、场景 `scene-desktop.webp`
| 项 | 值 |
| --- | --- |
| 画布 | 3840 × 2160（16:9），不透明 |
| 导出 | 1920 × 1080，WebP q82 |
| 色调 | 灰蓝／暖白，均值亮度 **235~245**，标准差 6~9（几乎是白雾） |
| 处理 | 整体压白 30~38%，高斯模糊 1.2~1.4px |
**构图硬约束（这条最容易翻车）：**
1. **左侧 0~22% 的前景必须是空地（地板）**，不能有课桌、椅子、书包。
人物是贴在最上层的独立图层，脚下必须有地面，否则会读成“站在课桌上”。
2. 课桌、椅子、黑板放在**中部偏右**，因为中间会被卡片完全盖住。
3. **不要有必须完整露出的元素**（`background-size: cover` 会按视口裁两侧，1080 高的屏裁掉约 5%）。
4. 不要出现人、文字、水印。自行车也不要画进背景——它要跟着人物一起移动。
5. 玻璃／窗框这类高频细节会干扰卡片可读性，右侧留白区尽量干净。
## 五、换图清单
1. 覆盖同名文件（格式 `WebP`，有透明的存 `q88`，场景存 `q82`）。
2. `static/css/themes/shiroko.css`：
- 若**显示尺寸不变**：只改三处 URL 的 `?v=`（图片不走 `StaticVersion`，缓存 1 天）。
- 若显示尺寸变了：改 `--tb-deco-size` 的 `auto 400px`（人） / `auto 259px`（车）。
3. `internal/conf/static.go` 的 `StaticVersion` +1（CSS 改了必须）。
4. 重新编译部署（静态资源是编译期 embed，只重启不重编不会变）。
### 定位公式（改比例时才需要算）
`background-position` 的百分比是相对 **(定位区宽 − 图片宽)**，不是视口宽：
```
实际 left = (视口宽 - 显示宽) × (pos%） + 偏移量
```
当前值（视口 1512 时：人物左沿 173px、车左沿 -55px，两者重叠区由人物遮住）：
```css
/* 人物：显示高 400，显示宽 = 400 × 0.293 ≈ 117 */
left: max(10px, calc(50% - 524px)) bottom 36px;
/* 车：显示高 259，显示宽 ≈ 397 */
left: calc(50% - 612px) bottom 20px;
```
## 六、验收（不看代码也能查）
1. **白边**：放大 300% 看轮廓，出现 1px 白色描边就是没抠干净。
2. **闭合区域**：手内侧、腿间、环心应能透出背景色。
3. **接地**：脚底／轮底离画布底边 ≤ 4px；有阴影时阴影在轮子内侧。
4. **体积**：人 ≤40KB、车 ≤40KB、场景 ≤40KB（现在分别是 15 / 29 / 19 KB）。
5. **深色模式**：所有图片在深色下都不显示，不用管。
6. **白上白**：车这类「白底 + 白主体」的素材，验收要额外看「不透明像素里近白（>240）的占比」——
正常应接近 0；本项目修复前是 **50%**，说明一半的不透明区域其实是背景白。
docs/theme-shiroko.md
-254
View File
@@ -1,254 +0,0 @@
# 主题「砂狼白子」（shiroko）
阿拜多斯学园风格的灰蓝／银白配色，附带 Q 版人物插画。启用方式：
```ini
[theme]
available = default,sakura,shiroko
```
箱主在「账号设置 → 主题外观」里选择即可。作用范围与其他主题一致：提问箱页面、本人投票页、`/user` 后台。
## 配色
| 令牌 | 浅色 | 深色 |
| --- | --- | --- |
| `--tb-bg` / `--tb-navbar` | `#edf2f8` | `#141a22` |
| `--tb-surface` | `#ffffff` | `#1d2530` |
| `--tb-surface-2` | `#e5ecf5` | `#273140` |
| `--tb-border` | `#d6e0ec` | `#334052` |
| `--tb-text` | `#222d3b` | `#e3eaf4` |
| `--tb-primary` | `#4a7fc1` | `#6fa3e0` |
## 视觉构图
参考对象：**蔚蓝档案 JP 官网首页**（`https://bluearchive.jp/`）。它的做法不是"白底 + 留白里贴几个人物"，
而是 **整个视口是一张场景插画，UI 浮在场景之上**。本主题照这个结构重排：
| 层 | 内容 | 实现 |
| --- | --- | --- |
| 底层 | 教室场景插画（压白 38%、轻度虚化） | `--tb-page-image`，16:9 桌面 / 9:16 移动两张 |
| 中层 | 卡片与顶栏：半透明白 + `backdrop-filter` 磨砂 | `--tb-surface: rgba(255,255,255,.86)` / `--tb-navbar` |
| 上层 | 人物站在场景左侧地面（400px 高）+ 椭圆接触阴影 | `--tb-deco` 前两个槽位 |
| 道具 | 她的自行车（车头朝右、与人同向）斜靠一把步枪 | `--tb-deco` 第 3 槽位 |
| 空气层 | 左窗光柱 / 右侧暖散景 / 脚下地面光斑 / 底部压深 | `--tb-deco` 第 4~7 槽位（全是渐变） |
> 装饰层共 10 个槽位（见 `internal/theme/slots_test.go`），本主题用前 7 个，其余留空。
> 想给某一页换装饰（例如问题页让人物退场），见 [theme-page-scope.md](theme-page-scope.md)。
| 深色 | 不用场景（白天教室压在深底上会脏），回到深色渐变 + 极淡纹样 | 深色块单独覆盖 |
摆位经验（都是踩过的）：
- **不要四角各摆一个人**。人物之间、人物与内容之间都没有关系，读起来就是贴纸墙纸；
人物必须"站在场景里"——有地面、有阴影、有环境，才不像贴纸。
- **右下角不能放人**。页脚文案右对齐（社区规则 / 备案号 / 存活时长），会和人物挤在一起。
- **离底边留 36px**。脚踩在窗口最后一行像素上会被读成"被裁切"，抬高之后必须配接触阴影，否则变成悬空。
- **纹样不要压在实景上**。平铺纹样叠在教室插画上会变成噪点，只在深色（无场景）时使用。
- **背景图会被 `cover` 裁切**，所以场景里不能有必须完整露出的元素：教室的黑板和窗户都在中部，裁掉两头不影响。
- **人物比例要跟场景对得上**。400px 是相对"站在前景"的尺度；缩到 240px 以下会显得像贴纸浮在半空。
### 空气层（2026-10-20 加）
场景压白 38% 之后整页亮度都在 235~246 之间，"再加点东西"直接摆物件一定会突兀。加了四层**纯渐变**：
| 槽位 | 作用 | 值 |
| --- | --- | --- |
| 3 | 左窗光柱（从左上斜下） | `linear-gradient(112deg, rgba(255,250,236,.50), transparent 44%)` |
| 4 | 右侧一朵暖散景（有体积感） | `radial-gradient(circle 120px at 88% 30%, rgba(255,252,240,.42), transparent 75%)` |
| 5 | 人物脚下的地面光斑（把她"钉"在地上） | `radial-gradient(ellipse 560px 170px at 28% 94%, rgba(255,248,228,.80), transparent 72%)` |
| 6 | 底部轻压深（下沿不飘） | `linear-gradient(0deg, rgba(110,128,156,.10), transparent 24%)` |
经验：
- 亮度差 **3~9 级**刚好能看出"有光"又不像打了聚光灯；超过 15 级就会读成一块脏。
- 白色散景压在已经压白的场景上等于没做（实测差异 0.14 级，肉眼不可见）——**要提亮就得先有暗部**，
所以真正起作用的是"压深 + 暖色光斑"的组合，不是加白。
- 所有槽位必须是单张图，**不能在一个槽位里塞逗号列表**（会让层数与 size/position 错位）。
- 8bit 渐变要检查阶梯：横向扫描线的相邻像素差应 ≤2~3；本次实测 max 4，无可见色阶。
> 尺寸 / 比例 / 雾度等可直接拿去外部工具复用的参数，见 [theme-shiroko-assets-spec.md](theme-shiroko-assets-spec.md)。
## 素材清单
位于 `static/images/themes/shiroko/`，已随二进制嵌入（`static/fs.go` 的 `images/themes`）。
| 文件 | 用途 | 尺寸 | 体积 |
| --- | --- | --- | --- |
| `chibi/window.webp` | **当前使用**：侧后方视角、双手背在身后望向箱内，压白 16% | 135×460 | 13KB |
| `props/bike.webp` | 自行车 + 步枪（车头朝右），压白 26% 后**只剩描边**（车身白填色已去掉，见下），自带接触阴影 | 397×259 | 29KB |
| `chibi/wave.webp` | 备用：正面挥手 | 324×620 | 27KB |
| `chibi/cheer.webp` | 双手欢呼 | 354×620 | 27KB |
| `chibi/think.webp` | 托腮 | 283×620 | 26KB |
| `chibi/doze.webp` | 打瞌睡 | 274×620 | 26KB |
| `scene-desktop.webp` | 教室场景（16:9，前景是空地，便于人物站立） | 1920×1080 | 19KB |
| `scene-mobile.webp` | 同一张场景的竖版裁切 | 720×1003 | 10KB |
| `pattern-dark.svg` | 深色模式平铺纹样（雪花 + 光环） | 240×240 | 0.7KB |
## 来源与授权
| 素材 | 来源 |
| --- | --- |
| 立绘参考图 | **用户自行用 AI 生成**，仅作 image-to-image 的 `image1`，不上页面、**不入库**（2026-10-21 移除，仓库里不存大图）|
| `chibi/window.webp` | WorkBuddy ImageGen 生成（文生图 → image-to-image 转平涂），再抠白底 |
| `chibi/wave.webp` 等 | WorkBuddy ImageGen **以用户立绘为参考图**（image-to-image）生成，再抠白底 |
| `scene-desktop.webp` / `scene-mobile.webp` | WorkBuddy ImageGen 生成（提示词见下），未使用任何外部素材 |
| `pattern-dark.svg` | 手写 SVG，纯几何，无外部素材 |
### 生成与抠图参数
- 参考图：用户提供的立绘（**不入库**，随便放个工作目录，传给 `image1` 即可），
`input_fidelity: high`，保证角色造型与平涂风格一致；
- 提示词骨架（四个姿态共用，只改动作句）：
> Same character, same art style as the reference image: flat vector illustration, no outlines,
> simple shapes, soft pastel colors, minimal detail. A chibi anime girl with short fluffy
> silver-grey bob hair, pointed grey wolf ears, a small tilted cyan halo ring above her head,
> pale blue dot eyes, cyan scarf, dark navy blazer, light grey pleated skirt, cyan and black
> sneakers. { 动作 } Plain pure white background (#FFFFFF), no shadow, no ground, no text, no watermark.
- 动作句：`Standing full body, front view, one arm raised waving hello with a small smile` /
`both arms raised up cheering happily, big smile` /
`one hand resting on her cheek thinking, head slightly tilted` /
`eyes closed sleeping peacefully, head drooping slightly to one side`；
- 抠图：从四角 + 四边中点共 8 点做 floodfill（容差 16），再对 alpha 做 1px MinFilter 收边去白边，
裁 bbox 后统一缩放到高 620、WebP q90。
### 当前人像（window.webp）的两步做法
正面立绘站在空教室里像贴纸（无环境、直视访客、饱和度高）。改成**侧后方视角 + 二次转平涂**：
1. 文生图先出姿势与角色：`flat vector chibi, three-quarter back view, hands clasped behind back,
short silver-grey bob, grey wolf ears, pale aqua fish-shaped halo, teal scarf, navy blazer,
grey pleated skirt, black and teal sneakers`（第一版带了教室窗框，背景处理不掉）；
2. 再把这张图扔回 image-to-image（`input_fidelity: high`）转成"纯色块、无描边、去掉窗框与场景，
纯白背景"，这样既保住姿势，又能拿到和立绘一致的平涂风格；
3. 光环单独重画：AI 给的光环不但形状歪，环内还是一块**封闭的白孔**——floodfill 只从四边漫水，
闭合区域进水不进去，抠完就是"环里糊着一团白"。做法是先把这个连通域（非白像素从环上一点漫水，
bbox 291,93–584,232，与头发不连通）整块抹白，抠完 alpha 后再用 PIL 画一个 -7° 倾斜的椭圆环
（4 倍超采样 + LANCZOS 缩小求平滑 + 一层 45% 的模糊柔光），环心天然是透明的；
4. 抠白底后把 RGB 压白 **16%**（`v*(1-k)+255*k`，alpha 不动）——场景本身压白 38%，
人像不压白就是全页对比度最高的一块，必然"突兀"；
5. 裁 bbox、缩到高 460，WebP q86（约 14KB）。
### 人物与道具必须用「同一套定位公式」
`background-position` 里的百分比**不是相对视口宽度**，而是相对 `(定位区宽 - 图片宽)`。
所以人物和自行车即使写同样的 `calc(50% - Npx)`，两者也会因为图宽不同而错位——
实测把车按人的公式放，车直接跑出屏幕，只剩一片轮圈。
正确做法是按各自宽度反解：设人物宽 `wc`、车宽 `wb`，要让车的右沿贴住人的左沿（留 gap）：
```
人的 left = (W - wc)/2 + Bc
车的 left = (W - wb)/2 + Bc - gap - wb + wc/2 - wc/2 ... 直接解 B 更省事
```
本主题实测：人物 `calc(50% - 524px)`、车 `calc(50% - 612px)`。
另外**道具不要烘焙进背景图**：背景是 `cover`，视口一变裁切量就变，
而人物是固定 px 定位的，两者必然分家。烘焙只适合「和人无关的背景物件」。
关键经验：**必须是"平涂无描边"**。先试过用手写 SVG 线稿，风格和用户那张立绘（色块、无描边）冲突，
而且没有真人手感会画得很抽象；用参考图 + image-to-image 出来的四张，角色特征和画风都稳。
**版权说明**：砂狼白子（砂狼シロコ）是《蔚蓝档案》的角色，版权归 NEXON Games / Yostar。
本主题为**非商用同人装饰**，仅作个人站点外观使用；若站点转为商业用途，请自行取得授权或换成原创素材。
## 替换 / 扩素材
1. 加姿态：按上面的提示词骨架换动作句生成，白底 → 抠图 → 存 `chibi/<name>.webp`（高 620），
再塞进 `shiroko.css` 的 `--tb-deco`（**必须保持 10 个值**，`--tb-deco-size` / `-position` 同步补齐，
少写几个不会报错、只会让图层与尺寸错位；`TestDecoSlotCount` 会拦），并按上面的摆位原则定位。
换 `<img>` 时别忘了给 URL 带 `?v=`——图片不走 `StaticVersion` 缓存键，`max-age` 是 1 天。
2. 换立绘：准备一张透明 PNG 立绘当参考图（不入库），再按同一提示词骨架重新生成姿态。
3. 换配色：改 `shiroko.css` 的令牌即可，插画是位图，换色需重新生成。
4. 新增素材不需要改 `static/fs.go`（已嵌整个 `images/themes` 目录）；但改了 CSS 必须把
`conf.StaticVersion` +1，否则老访客吃缓存看不到变化。
## 部署后设置页看不到这个主题？
先分两步确认，不要一上来就怀疑缓存：
1. **文件是否随二进制发布了** —— 直接取一次静态资源：
```bash
curl -o /dev/null -w "%{http_code}\n" \
https://<你的域名>/static/css/themes/shiroko.css?v=<StaticVersion>
```
返回 200 说明 css 已经嵌进去了；返回 404 说明部署的是旧二进制。
2. **是否登记进 `[theme] available`** —— 主题列表是启动时按白名单构建的，
css 在但没登记，设置页就看不到它。检查 `conf/app.ini`：
```ini
[theme]
default = default
available = default,sakura,shiroko
```
改完**重启**进程（`[theme]` 只在启动时读）。
启动日志会直接告诉你缺哪一行：
```
level=info msg="主题注册表已加载" enabled="default,sakura"
level=warning msg="[theme] available 未登记以下主题，它们不会出现在设置页"
available="default,sakura,shiroko" themes=shiroko
```
## 场景图的生成
整页背景是一张生成的教室插画，提示词：
```
Empty Japanese high school classroom in the afternoon, flat pastel anime background art,
very light and airy, pale blue-grey and warm cream palette, rows of desks softly out of focus,
big windows with soft daylight, thin clean shapes, low contrast, minimal detail,
large calm empty area in the center, no characters, no text, no watermark,
wide scene suitable as a website background
```
生成后处理（PIL，脚本未入库，参数记在这里）：
1. 裁掉图片底部 160px —— 生成器会在右下角打 `AI生成 WORKBUDDY` 水印，不裁会出现在页面上；
2. 按 16:9 取顶部 864px，整体混白 38%（`v*0.62 + 255*0.38`）—— 保证白卡片放上去仍有足够对比度；
3. 高斯模糊 1.4px，让桌椅不抢正文；
4. 导出 WebP q80（1920×1080，22KB）；移动端从同一张按 9:16 中裁 620px 宽，导出 720×1003。
## 肖像素材（平涂极简风）
`static/images/themes/shiroko/portraits/` 下另有一组独立肖像，风格参照用户给的参考图：
**平涂、零描边、纯黑圆角矩形眼、无嘴、腮红、头占满画面并裁边**。已抠成透明底，可直接叠在任何底色上。
| 文件 | 构图 | 尺寸 | 体积 |
| --- | --- | --- | --- |
| `portrait-front.webp` | 正面胸像，含深蓝外套与青色领结 | 907×921 | 66KB |
| `portrait-tilt.webp` | 头微侧、眼睛偏横向，气质更松 | 975×921 | 61KB |
| `portrait-close.webp` | 极限特写，头顶与两侧被画框切掉 | 1024×921 | 70KB |
用法（和背景装饰同一套槽位）：
```css
--tb-deco: url("/static/images/themes/shiroko/portraits/portrait-front.webp"), none, none, none, none, none;
--tb-deco-size: auto 320px, auto, auto, auto, auto, auto;
--tb-deco-position: left 0 bottom 0, left top, left top, left top, left top, left top;
```
注意：
- 底部是**平直切口**（原图右下角有水印，统一裁掉底部 10%），适合直接贴到页面下沿或卡片边缘，
不会出现"人浮在半空"的软边；
- 透明边缘是 1px 抗锯齿羽化，深色底上会有一圈极淡的浅边，浅色底上看不出来；
- 生成用的提示词骨架：
> Flat vector illustration, modern minimal poster style, no outlines, no gradients,
> only flat solid color shapes … 角色描述 … Eyes are solid black vertically elongated
> rounded rectangles, no highlights, no pupils, soft pink oval blush, no mouth.
> The background is one flat solid pale blue-grey color #E6EEF8.
关键三点：① 必须强调 **no outlines / no gradients**；② 眼睛要写死成**纯黑色块**，否则会画出
白眼球和高光；③ 背景指定**一个具体的纯色**（不要写 white），抠图时按这个色值算 alpha 才干净 ——
白底会连白衬衫、光环内部一起吃掉，闭合光环里的白还填不到。
原始 1024 PNG 与几版备选留在 `outputs/portraits-raw/`（该目录被 gitignore，只在本机）。
go.mod
+9 -14
View File
@@ -1,13 +1,11 @@
module github.com/tamakyi/TamaBox
go 1.27.3
go 1.25.0
replace golang.org/x/image => golang.org/x/image v0.13.0
require (
github.com/alibabacloud-go/darabonba-openapi/v2 v2.2.4
github.com/alibabacloud-go/green-20220302/v3 v3.5.4
github.com/alibabacloud-go/tea v1.5.2
github.com/aliyun/alibaba-cloud-sdk-go v1.62.26
github.com/aliyun/aliyun-oss-go-sdk v2.2.4+incompatible
github.com/aws/aws-sdk-go-v2 v1.24.0
github.com/aws/aws-sdk-go-v2/config v1.26.1
@@ -48,10 +46,9 @@ require (
go.opentelemetry.io/otel/sdk v1.9.0
go.opentelemetry.io/otel/trace v1.10.0
golang.org/x/crypto v0.54.0
golang.org/x/image v0.13.0
golang.org/x/net v0.56.0
gopkg.in/gomail.v2 v2.0.0-20160411212932-81ebce5c23df
gopkg.in/ini.v1 v1.67.0
gopkg.in/ini.v1 v1.66.2
gorm.io/datatypes v1.0.7
gorm.io/driver/mysql v1.3.6
gorm.io/driver/postgres v1.4.5
@@ -61,10 +58,6 @@ require (
require (
filippo.io/edwards25519 v1.1.0 // indirect
github.com/alecthomas/participle/v2 v2.0.0 // indirect
github.com/alibabacloud-go/alibabacloud-gateway-spi v0.0.5 // indirect
github.com/alibabacloud-go/debug v1.0.1 // indirect
github.com/alibabacloud-go/tea-utils/v2 v2.0.9 // indirect
github.com/aliyun/credentials-go v1.4.5 // indirect
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 // indirect
github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.5.4 // indirect
github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.14.10 // indirect
@@ -88,7 +81,6 @@ require (
github.com/charmbracelet/lipgloss v0.13.0 // indirect
github.com/charmbracelet/log v0.2.3 // indirect
github.com/charmbracelet/x/ansi v0.3.2 // indirect
github.com/clbanning/mxj/v2 v2.7.0 // indirect
github.com/cpuguy83/go-md2man/v2 v2.0.3 // indirect
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
@@ -98,8 +90,8 @@ require (
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-redis/redis/v8 v8.11.5 // indirect
github.com/golang/protobuf v1.5.3 // indirect
github.com/gopherjs/gopherjs v0.0.0-20190430165422-3e4dfb77656c // indirect
github.com/gorilla/css v1.0.1 // indirect
github.com/gorilla/websocket v1.5.3 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.11.3 // indirect
github.com/jackc/chunkreader/v2 v2.0.1 // indirect
github.com/jackc/pgio v1.0.0 // indirect
@@ -110,6 +102,7 @@ require (
github.com/jackc/pgx/v4 v4.17.2 // indirect
github.com/jinzhu/inflection v1.0.0 // indirect
github.com/jinzhu/now v1.1.5 // indirect
github.com/jmespath/go-jmespath v0.4.0 // indirect
github.com/json-iterator/go v1.1.12 // indirect
github.com/kr/pretty v0.3.1 // indirect
github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
@@ -121,20 +114,21 @@ require (
github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
github.com/muesli/termenv v0.15.3-0.20240618155329-98d742f6907a // indirect
github.com/onsi/gomega v1.29.0 // indirect
github.com/opentracing/opentracing-go v1.2.1-0.20220228012449-10b1cf09e00b // indirect
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
github.com/projectdiscovery/blackrock v0.0.2 // indirect
github.com/projectdiscovery/retryabledns v1.0.115 // indirect
github.com/projectdiscovery/utils v0.11.1 // indirect
github.com/redis/go-redis/v9 v9.5.1
github.com/redis/go-redis/v9 v9.5.1 // indirect
github.com/richardlehane/mscfb v1.0.4 // indirect
github.com/richardlehane/msoleps v1.0.1 // indirect
github.com/rivo/uniseg v0.4.7 // indirect
github.com/saintfish/chardet v0.0.0-20230101081208-5e3ef4b5456d // indirect
github.com/smartystreets/assertions v1.0.1 // indirect
github.com/tdewolff/parse/v2 v2.6.4 // indirect
github.com/tidwall/gjson v1.18.0 // indirect
github.com/tidwall/match v1.2.0 // indirect
github.com/tidwall/pretty v1.2.1 // indirect
github.com/tjfoc/gmsm v1.4.1 // indirect
github.com/uptrace/opentelemetry-go-extra/otelsql v0.1.16 // indirect
github.com/uptrace/opentelemetry-go-extra/otelutil v0.1.16 // indirect
github.com/weppos/publicsuffix-go v0.50.3-0.20260104170930-90713dec78f2 // indirect
@@ -152,6 +146,7 @@ require (
go.opentelemetry.io/proto/otlp v0.19.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
golang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect
golang.org/x/image v0.13.0 // indirect
golang.org/x/mod v0.37.0 // indirect
golang.org/x/sync v0.22.0 // indirect
golang.org/x/sys v0.47.0 // indirect
go.sum
+24 -116
View File
@@ -50,54 +50,10 @@ github.com/alecthomas/participle/v2 v2.0.0/go.mod h1:rAKZdJldHu8084ojcWevWAL8KmE
github.com/alecthomas/repr v0.0.0-20181024024818-d37bc2a10ba1/go.mod h1:xTS7Pm1pD1mvyM075QCDSRqH6qRLXylzS24ZTpRiSzQ=
github.com/alecthomas/repr v0.2.0 h1:HAzS41CIzNW5syS8Mf9UwXhNH1J9aix/BvDRf1Ml2Yk=
github.com/alecthomas/repr v0.2.0/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
github.com/alibabacloud-go/alibabacloud-gateway-pop v0.0.6 h1:eIf+iGJxdU4U9ypaUfbtOWCsZSbTb8AUHvyPrxu6mAA=
github.com/alibabacloud-go/alibabacloud-gateway-pop v0.0.6/go.mod h1:4EUIoxs/do24zMOGGqYVWgw0s9NtiylnJglOeEB5UJo=
github.com/alibabacloud-go/alibabacloud-gateway-spi v0.0.4/go.mod h1:sCavSAvdzOjul4cEqeVtvlSaSScfNsTQ+46HwlTL1hc=
github.com/alibabacloud-go/alibabacloud-gateway-spi v0.0.5 h1:zE8vH9C7JiZLNJJQ5OwjU9mSi4T9ef9u3BURT6LCLC8=
github.com/alibabacloud-go/alibabacloud-gateway-spi v0.0.5/go.mod h1:tWnyE9AjF8J8qqLk645oUmVUnFybApTQWklQmi5tY6g=
github.com/alibabacloud-go/darabonba-array v0.1.0 h1:vR8s7b1fWAQIjEjWnuF0JiKsCvclSRTfDzZHTYqfufY=
github.com/alibabacloud-go/darabonba-array v0.1.0/go.mod h1:BLKxr0brnggqOJPqT09DFJ8g3fsDshapUD3C3aOEFaI=
github.com/alibabacloud-go/darabonba-encode-util v0.0.2 h1:1uJGrbsGEVqWcWxrS9MyC2NG0Ax+GpOM5gtupki31XE=
github.com/alibabacloud-go/darabonba-encode-util v0.0.2/go.mod h1:JiW9higWHYXm7F4PKuMgEUETNZasrDM6vqVr/Can7H8=
github.com/alibabacloud-go/darabonba-map v0.0.2 h1:qvPnGB4+dJbJIxOOfawxzF3hzMnIpjmafa0qOTp6udc=
github.com/alibabacloud-go/darabonba-map v0.0.2/go.mod h1:28AJaX8FOE/ym8OUFWga+MtEzBunJwQGceGQlvaPGPc=
github.com/alibabacloud-go/darabonba-openapi/v2 v2.2.4 h1:o6veen0IZ/Fe1JawwhwQMZcbw67CVDY1pQwXcNWPyQo=
github.com/alibabacloud-go/darabonba-openapi/v2 v2.2.4/go.mod h1:eHjVxrT9g8uVYN/nyAwOFQEfkVA154ChiqRc2XnNKYU=
github.com/alibabacloud-go/darabonba-signature-util v0.0.7 h1:UzCnKvsjPFzApvODDNEYqBHMFt1w98wC7FOo0InLyxg=
github.com/alibabacloud-go/darabonba-signature-util v0.0.7/go.mod h1:oUzCYV2fcCH797xKdL6BDH8ADIHlzrtKVjeRtunBNTQ=
github.com/alibabacloud-go/darabonba-string v1.0.2 h1:E714wms5ibdzCqGeYJ9JCFywE5nDyvIXIIQbZVFkkqo=
github.com/alibabacloud-go/darabonba-string v1.0.2/go.mod h1:93cTfV3vuPhhEwGGpKKqhVW4jLe7tDpo3LUM0i0g6mA=
github.com/alibabacloud-go/debug v0.0.0-20190504072949-9472017b5c68/go.mod h1:6pb/Qy8c+lqua8cFpEy7g39NRRqOWc3rOwAy8m5Y2BY=
github.com/alibabacloud-go/debug v1.0.0/go.mod h1:8gfgZCCAC3+SCzjWtY053FrOcd4/qlH6IHTI4QyICOc=
github.com/alibabacloud-go/debug v1.0.1 h1:MsW9SmUtbb1Fnt3ieC6NNZi6aEwrXfDksD4QA6GSbPg=
github.com/alibabacloud-go/debug v1.0.1/go.mod h1:8gfgZCCAC3+SCzjWtY053FrOcd4/qlH6IHTI4QyICOc=
github.com/alibabacloud-go/endpoint-util v1.1.0 h1:r/4D3VSw888XGaeNpP994zDUaxdgTSHBbVfZlzf6b5Q=
github.com/alibabacloud-go/endpoint-util v1.1.0/go.mod h1:O5FuCALmCKs2Ff7JFJMudHs0I5EBgecXXxZRyswlEjE=
github.com/alibabacloud-go/green-20220302/v3 v3.5.4 h1:ZnlHri7tTLl28JWB5S2J6MYvD0ewJFI7hedK4E7+gSk=
github.com/alibabacloud-go/green-20220302/v3 v3.5.4/go.mod h1:PQTtoEuWOsuq7H7sgTRcXDw4Ut/Hekgy5z2mWGtO9OQ=
github.com/alibabacloud-go/openapi-util v0.1.0 h1:0z75cIULkDrdEhkLWgi9tnLe+KhAFE/r5Pb3312/eAY=
github.com/alibabacloud-go/openapi-util v0.1.0/go.mod h1:sQuElr4ywwFRlCCberQwKRFhRzIyG4QTP/P4y1CJ6Ws=
github.com/alibabacloud-go/tea v1.1.0/go.mod h1:IkGyUSX4Ba1V+k4pCtJUc6jDpZLFph9QMy2VUPTwukg=
github.com/alibabacloud-go/tea v1.1.7/go.mod h1:/tmnEaQMyb4Ky1/5D+SE1BAsa5zj/KeGOFfwYm3N/p4=
github.com/alibabacloud-go/tea v1.1.8/go.mod h1:/tmnEaQMyb4Ky1/5D+SE1BAsa5zj/KeGOFfwYm3N/p4=
github.com/alibabacloud-go/tea v1.1.11/go.mod h1:/tmnEaQMyb4Ky1/5D+SE1BAsa5zj/KeGOFfwYm3N/p4=
github.com/alibabacloud-go/tea v1.1.17/go.mod h1:nXxjm6CIFkBhwW4FQkNrolwbfon8Svy6cujmKFUq98A=
github.com/alibabacloud-go/tea v1.1.20/go.mod h1:nXxjm6CIFkBhwW4FQkNrolwbfon8Svy6cujmKFUq98A=
github.com/alibabacloud-go/tea v1.2.2/go.mod h1:CF3vOzEMAG+bR4WOql8gc2G9H3EkH3ZLAQdpmpXMgwk=
github.com/alibabacloud-go/tea v1.5.2 h1:DUzV/cRTbJC++rmADfqVu//GuWbaD64ZJ3yW3v2ukNU=
github.com/alibabacloud-go/tea v1.5.2/go.mod h1:hgSs82CkOiehSQMoiFN79dL6zsGX7pVGvnn9SIEs8/0=
github.com/alibabacloud-go/tea-utils v1.3.1 h1:iWQeRzRheqCMuiF3+XkfybB3kTgUXkXX+JMrqfLeB2I=
github.com/alibabacloud-go/tea-utils v1.3.1/go.mod h1:EI/o33aBfj3hETm4RLiAxF/ThQdSngxrpF8rKUDJjPE=
github.com/alibabacloud-go/tea-utils/v2 v2.0.5/go.mod h1:dL6vbUT35E4F4bFTHL845eUloqaerYBYPsdWR2/jhe4=
github.com/alibabacloud-go/tea-utils/v2 v2.0.9 h1:y6pUIlhjxbZl9ObDAcmA1H3c21eaAxADHTDQmBnAIgA=
github.com/alibabacloud-go/tea-utils/v2 v2.0.9/go.mod h1:qxn986l+q33J5VkialKMqT/TTs3E+U9MJpd001iWQ9I=
github.com/aliyun/alibaba-cloud-sdk-go v1.62.26 h1:WvhbWN/8MqYY20LVi6vqkZ1ZHUibvnUoV9IF4jKA/Kw=
github.com/aliyun/alibaba-cloud-sdk-go v1.62.26/go.mod h1:Api2AkmMgGaSUAhmk76oaFObkoeCPc/bKAqcyplPODs=
github.com/aliyun/aliyun-oss-go-sdk v2.2.4+incompatible h1:cD1bK/FmYTpL+r5i9lQ9EU6ScAjA173EVsii7gAc6SQ=
github.com/aliyun/aliyun-oss-go-sdk v2.2.4+incompatible/go.mod h1:T/Aws4fEfogEE9v+HPhhw+CntffsBHJ8nXQCwKr0/g8=
github.com/aliyun/credentials-go v1.1.2/go.mod h1:ozcZaMR5kLM7pwtCMEpVmQ242suV6qTJya2bDq4X1Tw=
github.com/aliyun/credentials-go v1.3.1/go.mod h1:8jKYhQuDawt8x2+fusqa1Y6mPxemTsBEN04dgcAcYz0=
github.com/aliyun/credentials-go v1.3.6/go.mod h1:1LxUuX7L5YrZUWzBrRyk0SwSdH4OmPrib8NVePL3fxM=
github.com/aliyun/credentials-go v1.4.5 h1:O76WYKgdy1oQYYiJkERjlA2dxGuvLRrzuO2ScrtGWSk=
github.com/aliyun/credentials-go v1.4.5/go.mod h1:Jm6d+xIgwJVLVWT561vy67ZRP4lPTQxMbEYRuT2Ti1U=
github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY=
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 h1:DklsrG3dyBCFEj5IhUbnKptjxatkF07cF2ak3yi77so=
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw=
@@ -169,8 +125,6 @@ github.com/cheekybits/is v0.0.0-20150225183255-68e9c0620927/go.mod h1:h/aW8ynjgk
github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
github.com/clbanning/mxj/v2 v2.7.0 h1:WA/La7UGCanFe5NpHF0Q3DNtnCsVoxbPKuyBNHWRyME=
github.com/clbanning/mxj/v2 v2.7.0/go.mod h1:hNiWqW14h+kc+MdF9C6/YoRfjEJoR3ou6tn/Qo+ve2s=
github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
github.com/cncf/udpa/go v0.0.0-20201120205902-5459f2c99403/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
@@ -256,6 +210,7 @@ github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/me
github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE=
github.com/gofrs/uuid v4.0.0+incompatible h1:1SD/1F5pU8p29ybwgQSwpQk+mwdRrXCYuPhW6m+TnJw=
github.com/gofrs/uuid v4.0.0+incompatible/go.mod h1:b2aQJv3Z4Fp6yNu3cdSllBxTCLRxnplIgP/c0N/04lM=
github.com/goji/httpauth v0.0.0-20160601135302-2da839ab0f4d/go.mod h1:nnjvkQ9ptGaCkuDUx6wNykzzlUixGxvkme+H/lnzb+A=
github.com/golang-sql/civil v0.0.0-20190719163853-cb61b32ac6fe/go.mod h1:8vg3r2VgvsThLBIFL93Qb5yWzgyZWhEmBwUJWevAkK0=
github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9 h1:au07oEsX2xN0ktxqI+Sida1w446QrXBRJ0nee3SNZlA=
github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9/go.mod h1:8vg3r2VgvsThLBIFL93Qb5yWzgyZWhEmBwUJWevAkK0=
@@ -326,12 +281,10 @@ github.com/googleapis/gax-go/v2 v2.0.4/go.mod h1:0Wqv26UfaUD9n4G6kQubkQ+KchISgw+
github.com/googleapis/gax-go/v2 v2.0.5/go.mod h1:DWXyrwAJ9X0FpwwEdw+IPEYBICEFu5mhpdKc/us6bOk=
github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
github.com/gopherjs/gopherjs v0.0.0-20181103185306-d547d1d9531e/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
github.com/gopherjs/gopherjs v0.0.0-20200217142428-fce0ec30dd00 h1:l5lAOZEym3oK3SQ2HBHWsJUfbNBiTXJDeW2QDxw9AQ0=
github.com/gopherjs/gopherjs v0.0.0-20200217142428-fce0ec30dd00/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
github.com/gopherjs/gopherjs v0.0.0-20190430165422-3e4dfb77656c h1:7lF+Vz0LqiRidnzC1Oq86fpX1q/iEv2KJdrCtttYjT4=
github.com/gopherjs/gopherjs v0.0.0-20190430165422-3e4dfb77656c/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
github.com/grpc-ecosystem/grpc-gateway v1.16.0/go.mod h1:BDjrQk3hbvj6Nolgz8mAMFbcEtjT1g+wF4CSlocrBnw=
github.com/grpc-ecosystem/grpc-gateway/v2 v2.7.0/go.mod h1:hgWBS7lorOAVIJEQMi4ZsPv9hVvWI6+ch50m39Pf2Ks=
github.com/grpc-ecosystem/grpc-gateway/v2 v2.11.3 h1:lLT7ZLSzGLI08vc9cpd+tYmNWjdKDqyr/2L+f6U12Fk=
@@ -403,7 +356,12 @@ github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkr
github.com/jinzhu/now v1.1.4/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
github.com/json-iterator/go v1.1.10/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
github.com/jmespath/go-jmespath v0.0.0-20180206201540-c2b33e8439af/go.mod h1:Nht3zPeWKUH0NzdCt2Blrr5ys8VGpn0CEB0cQHVjt7k=
github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg=
github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo=
github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8=
github.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U=
github.com/json-iterator/go v1.1.5/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU=
github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1:6v2b51hI/fHJwM22ozAgKL4VKDeJcHhJFhtBdhmNjmU=
@@ -452,7 +410,6 @@ github.com/miekg/dns v1.1.72/go.mod h1:+EuEPhdHOsfk6Wk5TT2CzssZdqkmFhf8r+aVyDETo
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
@@ -462,7 +419,6 @@ github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwd
github.com/montanaflynn/stats v0.0.0-20171201202039-1bf9dbcd8cbe/go.mod h1:wL8QJuTMNUDYhXwkmfOly8iTdp5TEcJFWZD2D7SIkUc=
github.com/muesli/termenv v0.15.3-0.20240618155329-98d742f6907a h1:2MaM6YC3mGu54x+RKAA6JiFFHlHDY1UbkxqppT7wYOg=
github.com/muesli/termenv v0.15.3-0.20240618155329-98d742f6907a/go.mod h1:hxSnBBYLK21Vtq/PHd0S2FYCxBXzBua8ov5s1RobyRQ=
github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
github.com/nxadm/tail v1.4.11 h1:8feyoE3OzPrcshW5/MJ4sGESc5cqmGkGCWlco4l0bqY=
@@ -477,6 +433,8 @@ github.com/onsi/gomega v1.10.1/go.mod h1:iN09h71vgCQne3DLsj+A5owkum+a2tYe+TOCB1y
github.com/onsi/gomega v1.16.0/go.mod h1:HnhC7FXeEQY45zxNK3PPoIUhzk/80Xly9PcubAlGdZY=
github.com/onsi/gomega v1.29.0 h1:KIA/t2t5UBzoirT4H9tsML45GEbo3ouUnBHsCfD2tVg=
github.com/onsi/gomega v1.29.0/go.mod h1:9sxs+SwGrKI0+PWe4Fxa9tFQQBG5xSsSbMXOI8PPpoQ=
github.com/opentracing/opentracing-go v1.2.1-0.20220228012449-10b1cf09e00b h1:FfH+VrHHk6Lxt9HdVS0PXzSXFyS2NbZKXv33FYPol0A=
github.com/opentracing/opentracing-go v1.2.1-0.20220228012449-10b1cf09e00b/go.mod h1:AC62GU6hc0BrNm+9RK9VSiwa/EUe1bkIeFORAMcHvJU=
github.com/pkg/browser v0.0.0-20180916011732-0a3d74bf9ce4/go.mod h1:4OwLy04Bl9Ef3GJJCoec+30X3LQs/0/m4HFRt/2LUSA=
github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
@@ -536,8 +494,8 @@ github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1
github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
github.com/smartystreets/assertions v0.0.0-20190116191733-b6c0e53d7304/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
github.com/smartystreets/assertions v1.1.0 h1:MkTeG1DMwsrdH7QtLXy5W+fUxWq+vmb6cLmyJ7aRtF0=
github.com/smartystreets/assertions v1.1.0/go.mod h1:tcbTF8ujkAEcZ8TElKY+i30BzYlVhC/LOxJk7iOWnoo=
github.com/smartystreets/assertions v1.0.1 h1:voD4ITNjPL5jjBfgR/r8fPIIBrliWrWHeiJApdr3r4w=
github.com/smartystreets/assertions v1.0.1/go.mod h1:kHHU4qYBaI3q23Pp3VPrmWhuIUrLW/7eUrw0BU5VaoM=
github.com/smartystreets/goconvey v0.0.0-20181108003508-044398e4856c/go.mod h1:XDJAKZRPZ1CvBcN2aX5YOUTYGHki24fSF0Iv48Ibg0s=
github.com/smartystreets/goconvey v1.6.4 h1:fv0U8FUIMPNf1L9lnHLvLhgicrIVChEkdzIKYqbNC9s=
github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
@@ -576,9 +534,10 @@ github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhV
github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
github.com/tjfoc/gmsm v1.3.2/go.mod h1:HaUcFuY0auTiaHB9MHFGCPx5IaLhTUd2atbCFBQXn9w=
github.com/tjfoc/gmsm v1.4.1 h1:aMe1GlZb+0bLjn+cKTPEvvn9oUEBlJitaZiiBwsbgho=
github.com/tjfoc/gmsm v1.4.1/go.mod h1:j4INPkHWMrhJb38G+J6W4Tw0AbuN8Thu3PbdVYhVcTE=
github.com/uber/jaeger-client-go v2.30.0+incompatible h1:D6wyKGCecFaSRUpo8lCVbaOOb6ThwMmTEbhRwtKR97o=
github.com/uber/jaeger-client-go v2.30.0+incompatible/go.mod h1:WVhlPFC8FDjOFMMWRy2pZqQJSXxYSwNYOkTr/Z6d3Kk=
github.com/uber/jaeger-lib v2.4.1+incompatible h1:td4jdvLcExb4cBISKIpHuGoVXh+dVKhn2Um6rjCsSsg=
github.com/uber/jaeger-lib v2.4.1+incompatible/go.mod h1:ComeNDZlWwrWnDv8aPp0Ba6+uUTzImX/AauajbLI56U=
github.com/unknwon/com v1.0.1 h1:3d1LTxD+Lnf3soQiD4Cp/0BRB+Rsa/+RTvz8GMMzIXs=
github.com/unknwon/com v1.0.1/go.mod h1:tOOxU81rwgoCLoOVVPHb6T/wt8HZygqH5id+GNnlCXM=
github.com/uptrace/opentelemetry-go-extra/otelgorm v0.1.16 h1:WBsTsLkHGaURNRsEGpJY3FxfNOId6u9fl7H/ST6UwBc=
@@ -613,7 +572,6 @@ github.com/xuri/nfp v0.0.0-20220409054826-5e722a1d9e22/go.mod h1:WwHg+CVyzlv/TX9
github.com/youmark/pkcs8 v0.0.0-20181117223130-1be2e3e5546d/go.mod h1:rHwXgn7JulP+udvsHwJoVG1YGAP6VLg4y9I5dyZdqmA=
github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.1.30/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
@@ -655,6 +613,8 @@ go.uber.org/atomic v1.3.2/go.mod h1:gD2HeocX3+yG+ygLZcrzQJaqmWj9AIm7n08wl/qW/PE=
go.uber.org/atomic v1.4.0/go.mod h1:gD2HeocX3+yG+ygLZcrzQJaqmWj9AIm7n08wl/qW/PE=
go.uber.org/atomic v1.5.0/go.mod h1:sABNBOSYdrvTF6hTgEIbc7YasKWGhgEQZyfxyTvoXHQ=
go.uber.org/atomic v1.6.0/go.mod h1:sABNBOSYdrvTF6hTgEIbc7YasKWGhgEQZyfxyTvoXHQ=
go.uber.org/atomic v1.9.0 h1:ECmE8Bn/WFTYwEW/bpKD3M8VtR/zQVbavAoalC1PYyE=
go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc=
go.uber.org/goleak v1.1.12 h1:gZAh5/EyT/HQwlpkCy6wTpqfH9H8Lz8zbm3dZh+OyzA=
go.uber.org/goleak v1.1.12/go.mod h1:cwTWslyiVhfpKIDGSZEM2HlOvcqm+tG4zioyIeLoqMQ=
go.uber.org/multierr v1.1.0/go.mod h1:wR5kodmAFQ0UK8QlbwjlSNy0Z68gJhDJUG5sjR94q/0=
@@ -672,10 +632,7 @@ golang.org/x/crypto v0.0.0-20190510104115-cbcb75029529/go.mod h1:yigFU9vqHzYiE8U
golang.org/x/crypto v0.0.0-20190605123033-f99c8df09eb5/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
golang.org/x/crypto v0.0.0-20190820162420-60c769a6c586/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
golang.org/x/crypto v0.0.0-20191219195013-becbf705a915/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20200510223506-06a226fb4e37/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20201012173705-84dcc777aaee/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20201016220609-9e8e0b390897/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20201203163018-be400aefbc4c/go.mod h1:jdWPYTVW3xRLrWPugEBEK3UY2ZEsg3UU495nc5E+M+I=
golang.org/x/crypto v0.0.0-20201216223049-8b5274cf687f/go.mod h1:jdWPYTVW3xRLrWPugEBEK3UY2ZEsg3UU495nc5E+M+I=
@@ -685,13 +642,6 @@ golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5y
golang.org/x/crypto v0.0.0-20220214200702-86341886e292/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
golang.org/x/crypto v0.0.0-20220408190544-5352b0902921/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
golang.org/x/crypto v0.0.0-20220722155217-630584e8d5aa/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
golang.org/x/crypto v0.14.0/go.mod h1:MVFd36DqK4CsrnJYDkBA3VC4m2GkXAM0PvzMCn4JQf4=
golang.org/x/crypto v0.18.0/go.mod h1:R0j02AL6hcrfOiy9T4ZYp/rcWeMxM3L6QYxlOuEG1mg=
golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
golang.org/x/crypto v0.21.0/go.mod h1:0BP7YvVV9gBbVKyeTG0Gyn+gZm94bibOW5BjDEYAOMs=
golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
golang.org/x/crypto v0.24.0/go.mod h1:Z1PMYSOR5nyMcyAVAIQSKCDwalqy85Aqn1x3Ws4L5DM=
golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
@@ -728,9 +678,6 @@ golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
@@ -762,7 +709,6 @@ golang.org/x/net v0.0.0-20200520182314-0ba52f642ac2/go.mod h1:qpuaurCH72eLCgpAm/
golang.org/x/net v0.0.0-20200625001655-4c5254603344/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA=
golang.org/x/net v0.0.0-20200707034311-ab3426394381/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA=
golang.org/x/net v0.0.0-20200822124328-c89045814202/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA=
golang.org/x/net v0.0.0-20201010224723-4f7140c49acb/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
@@ -772,15 +718,6 @@ golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qx
golang.org/x/net v0.0.0-20220407224826-aac1ed45d8e3/go.mod h1:CfG3xpIq0wQ8r1q4Su4UZFWDARRcnwPjda9FqA0JpMk=
golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
golang.org/x/net v0.20.0/go.mod h1:z8BVo6PvndSri0LbOE3hAn0apkU+1YvI6E70E9jsnvY=
golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
golang.org/x/net v0.23.0/go.mod h1:JKghWKKOSdJwpW2GEx0Ja7fmaKnMsbu+MWVZTokSYmg=
golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE=
golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
@@ -801,9 +738,6 @@ golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJ
golang.org/x/sync v0.0.0-20201207232520-09787c993a3a/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
@@ -838,7 +772,6 @@ golang.org/x/sys v0.0.0-20200302150141-5c8b2ff67527/go.mod h1:h1NjWce9XRLGQEsW7w
golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200331124033-c3d80250170d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200501052902-10377860bb8e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200509044756-6aff5f38e54f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200511232937-7e40ca221e25/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200515095857-1151b9dac4a9/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200523222454-059865788121/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -859,29 +792,12 @@ golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBc
golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.16.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.21.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
golang.org/x/term v0.13.0/go.mod h1:LTmsnFJwVN6bCy1rVCoS+qHT1HhALEFxKncY3WNNh4U=
golang.org/x/term v0.16.0/go.mod h1:yn7UURbUtPyrVJPGPq404EukNFxcm/foM+bV/bfcDsY=
golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
golang.org/x/term v0.18.0/go.mod h1:ILwASektA3OnRv7amZ1xhE/KTR+u50pbXfZ03+6Nx58=
golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
golang.org/x/term v0.21.0/go.mod h1:ooXLefLobQVslOqselCNF4SxFAaoS6KujMbsGzSDmX0=
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/text v0.3.1-0.20180807135948-17ff2d5776d2/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
@@ -892,11 +808,7 @@ golang.org/x/text v0.3.5/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/text v0.16.0/go.mod h1:GhwF1Be+LQoKShO3cGOHzqOgRrGaYc9AvblQOmPVHnI=
golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
golang.org/x/time v0.0.0-20181108054448-85acf8d2951c/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
@@ -944,7 +856,6 @@ golang.org/x/tools v0.0.0-20200304193943-95d2e580d8eb/go.mod h1:o4KQGtdN14AW+yjs
golang.org/x/tools v0.0.0-20200312045724-11d5b4c81c7d/go.mod h1:o4KQGtdN14AW+yjsvvwRTJJuXz8XRtIHtEnmAXLyFUw=
golang.org/x/tools v0.0.0-20200331025713-a30bf2db82d4/go.mod h1:Sl4aGygMT6LrqrWclx+PTx3U+LnKx/seiNR+3G19Ar8=
golang.org/x/tools v0.0.0-20200501065659-ab2804fb9c9d/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
golang.org/x/tools v0.0.0-20200509030707-2212a7e161a5/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
golang.org/x/tools v0.0.0-20200512131952-2bc93b1c0c88/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
golang.org/x/tools v0.0.0-20200515010526-7d3b6ebf133d/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
golang.org/x/tools v0.0.0-20200618134242-20370b0cb4b2/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
@@ -954,8 +865,6 @@ golang.org/x/tools v0.0.0-20200825202427-b303f430e36d/go.mod h1:njjCfa9FT2d7l9Bc
golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
golang.org/x/xerrors v0.0.0-20190410155217-1f06c39b4373/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@@ -1060,7 +969,6 @@ gopkg.in/alexcesaro/quotedprintable.v3 v3.0.0-20150716171945-2caba252f4dc h1:2gG
gopkg.in/alexcesaro/quotedprintable.v3 v3.0.0-20150716171945-2caba252f4dc/go.mod h1:m7x9LTH6d71AHyAX77c9yqWCCa3UKHcVEj9y7hAtKDk=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
@@ -1068,9 +976,8 @@ gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMy
gopkg.in/gomail.v2 v2.0.0-20160411212932-81ebce5c23df h1:n7WqCuqOuCbNr617RXOY0AWRXxgwEyPp2z+p0+hgMuE=
gopkg.in/gomail.v2 v2.0.0-20160411212932-81ebce5c23df/go.mod h1:LRQQ+SO6ZHR7tOkpBDuZnXENFzX8qRjMDMyPD6BRkCw=
gopkg.in/inconshreveable/log15.v2 v2.0.0-20180818164646-67afb5ed74ec/go.mod h1:aPpfJ7XW+gOuirDoZ8gHhLh3kZ1B08FtV2bbmy7Jv3s=
gopkg.in/ini.v1 v1.56.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
gopkg.in/ini.v1 v1.66.2 h1:XfR1dOYubytKy4Shzc2LHrrGhU0lDCfDGG1yLPmpgsI=
gopkg.in/ini.v1 v1.66.2/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ=
gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
@@ -1078,6 +985,7 @@ gopkg.in/yaml.v2 v2.2.3/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
internal/cache/cache.go
Vendored
-33
View File
@@ -58,39 +58,6 @@ func (c *TTLCache) Get(key string) (interface{}, bool) {
return e.value, true
}
// GetWithExpiry 读取缓存值与其过期时间，**不判断、不删除**过期条目。
//
// 供 stale-while-revalidate 使用：调用方拿到过期的旧值后可以先返回给用户，
// 再在后台重算。Get 做不到这一点——它遇到过期项就直接删掉并返回 false，
// 于是「过期」和「不存在」变成同一个结果，调用方只能同步等待重算。
func (c *TTLCache) GetWithExpiry(key string) (value interface{}, expiresAt time.Time, ok bool) {
c.mu.RLock()
defer c.mu.RUnlock()
e, ok := c.items[key]
if !ok {
return nil, time.Time{}, false
}
return e.value, e.expiresAt, true
}
// Expire 把条目标记为「已过期」但**保留其值**。
//
// 与 Delete 的区别很关键：Delete 之后下次读是彻底 miss，调用方只能同步重算；
// Expire 之后下次读仍然拿得到旧值，于是可以「先返回旧值 + 后台刷新」。
// 写多读多的场景（例如投票：每来一票都要让结果失效）只有用 Expire 才不会
// 把每次写入都变成下一次读的同步 O(N) 重算。
// key 不存在或已过期时什么也不做。
func (c *TTLCache) Expire(key string) {
c.mu.Lock()
defer c.mu.Unlock()
e, ok := c.items[key]
if !ok {
return
}
e.expiresAt = time.Now().Add(-time.Second)
c.items[key] = e
}
// Set 写入缓存并设定过期时间。
func (c *TTLCache) Set(key string, value interface{}, ttl time.Duration) {
c.mu.Lock()
internal/cache/cache_test.go
Vendored
-66
View File
@@ -59,69 +59,3 @@ func TestTTLCacheConcurrent(t *testing.T) {
}
wg.Wait()
}
// TestTTLCacheGetWithExpiryKeepsEntry 锁住一个关键语义：
// GetWithExpiry **不删除**过期条目，否则 stale-while-revalidate 拿不到旧值，
// 只能退化成「过期即彻底 miss → 同步重算」，那正是投票结果 O(N²) 的成因。
func TestTTLCacheGetWithExpiryKeepsEntry(t *testing.T) {
c := NewTTLCache(8)
c.Set("k", "v", time.Nanosecond)
time.Sleep(2 * time.Millisecond)
v, exp, ok := c.GetWithExpiry("k")
if !ok {
t.Fatal("expired entry should still be readable via GetWithExpiry")
}
if v.(string) != "v" {
t.Fatalf("expected stale value v, got %v", v)
}
if !time.Now().After(exp) {
t.Fatal("entry should already be expired")
}
// 再读一次仍然在（证明上一次调用没有顺手删掉它）
if _, _, ok := c.GetWithExpiry("k"); !ok {
t.Fatal("GetWithExpiry must not evict the entry")
}
// 而普通 Get 仍按原语义返回 miss（并清掉它）
if _, ok := c.Get("k"); ok {
t.Fatal("Get should report miss for an expired entry")
}
}
// TestTTLCacheGetWithExpiryMissing 不存在的 key 必须返回 ok=false，
// 且不能凭空造出一个零值过期时间让调用方误判为「过期但有值」。
func TestTTLCacheGetWithExpiryMissing(t *testing.T) {
c := NewTTLCache(8)
if _, _, ok := c.GetWithExpiry("nope"); ok {
t.Fatal("expected miss for unknown key")
}
}
// TestTTLCacheExpireKeepsValue 锁住 Expire 与 Delete 的区别：
// Expire 后条目仍在（可拿到旧值并触发后台刷新），而 Delete 之后彻底 miss。
func TestTTLCacheExpireKeepsValue(t *testing.T) {
c := NewTTLCache(8)
c.Set("k", "v", time.Hour)
c.Expire("k")
v, exp, ok := c.GetWithExpiry("k")
if !ok || v.(string) != "v" {
t.Fatalf("Expire must keep the value, got %v %v", v, ok)
}
if !time.Now().After(exp) {
t.Fatal("Expire must push expiresAt into the past")
}
// 普通 Get 立刻视为过期
if _, ok := c.Get("k"); ok {
t.Fatal("Get should see the expired entry as a miss")
}
// 对不存在的 key 调用 Expire 不应 panic 也不应创建条目
c.Expire("absent")
if _, _, ok := c.GetWithExpiry("absent"); ok {
t.Fatal("Expire must not create an entry")
}
}
internal/captcha/math.go
+14 -6
View File
@@ -27,8 +27,10 @@ import (
)
const (
// Session key prefix for storing math captcha answers
sessionKeyPrefix = "math_captcha_"
captchaTTL = 5 * time.Minute
// TTL for each captcha in session
captchaTTL = 5 * time.Minute
// maxCaptchaAttempts 同一条验证码被尝试（含模态框预校验）的最大次数，
// 超过即销毁该验证码，迫使刷新，防止对答案做无限轮询爆破。
maxCaptchaAttempts = 5
@@ -50,6 +52,7 @@ type StoredAnswer struct {
// GenerateMath creates a new arithmetic captcha problem and stores the answer in session.
func GenerateMath(s session.Session) (*MathProblem, error) {
// Generate random operands
op1, err := rand.Int(rand.Reader, big.NewInt(90))
if err != nil {
return nil, errors.Wrap(err, "generate operand 1")
@@ -61,6 +64,7 @@ func GenerateMath(s session.Session) (*MathProblem, error) {
a := int(op1.Int64()) + 1 // 1-90
b := int(op2.Int64()) + 1 // 1-90
// Pick a random operator (+, -, *)
opIdx, err := rand.Int(rand.Reader, big.NewInt(3))
if err != nil {
return nil, errors.Wrap(err, "generate operator")
@@ -86,16 +90,18 @@ func GenerateMath(s session.Session) (*MathProblem, error) {
answer = a * b
}
// 生成唯一 ID
idBytes := make([]byte, 8)
if _, err := rand.Read(idBytes); err != nil {
return nil, errors.Wrap(err, "generate captcha id")
}
id := hex.EncodeToString(idBytes)
// 清理策略：flamego session 不支持遍历，无法主动清理过期条目。但验证码一次性消费
// （校验后立即删除）、每用户同时刻只生成 1 个新 key，session 过期后存储层整体清理，
// 泄漏可控。
// 清理策略说明：flamego session 接口不支持遍历，无法主动清理过期条目。
// 泄漏可控：验证码一次性消费（VerifyMath 校验后立即删除），
// 且每个用户同一时刻只生成 1 个新 key；session 本身过期后存储层整体清理。
// Store answer in session
key := sessionKeyPrefix + id
s.Set(key, StoredAnswer{
Answer: answer,
@@ -130,12 +136,14 @@ func VerifyMath(s session.Session, token string, lang string) (bool, error) {
return false, errors.New(i18n.T(lang, "captcha.errAnswerFormat"))
}
// Retrieve stored answer
key := sessionKeyPrefix + id
stored, ok := s.Get(key).(StoredAnswer)
if !ok {
return false, errors.New(i18n.T(lang, "captcha.errExpired"))
}
// Check expiry
if time.Since(stored.CreatedAt) > captchaTTL {
s.Delete(key)
return false, errors.New(i18n.T(lang, "captcha.errExpired"))
@@ -178,8 +186,8 @@ func VerifyOnly(s session.Session, id string, answer int) bool {
return subtle.ConstantTimeCompare([]byte(strconv.Itoa(answer)), []byte(strconv.Itoa(stored.Answer))) == 1
}
// sessionLang 从会话读取匿名用户显式选择的语言（语言偏好托管于 session 而非独立 lang
// cookie，避免被 session 中间件的 Set-Cookie 覆盖）；未设置时回退默认。
// sessionLang 从会话读取匿名用户显式选择的语言（与 Contexter 一致，语言偏好现托管于
// session 而非独立 lang cookie，避免被 session 中间件的 Set-Cookie 覆盖）；未设置时回退默认。
func sessionLang(s session.Session) string {
if v := s.Get("lang"); v != nil {
if str, ok := v.(string); ok && str != "" {
internal/cmd/backup.go
-585
View File
@@ -1,585 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
"github.com/urfave/cli/v2"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/storage"
)
const (
imageObjectAttemptTimeout = 60 * time.Second
imageObjectMaxAttempts = 3
imageObjectRetryBackoff = 100 * time.Millisecond
)
// Backup 全量备份数据库与对象存储（Cloudflare R2）图片到本地目录。
//
// 为什么必须同时备份图片：站点的所有图片（头像 / 背景 / 二维码 logo / 提问图 / 回答图）
// 都以根日期 key、picture/ 或 tamabox/ 等形式存在 R2 上，数据库里只存 key 或 CDN URL。
// 只备份数据库的话，恢复后这些引用指向的图片若已不在 R2，页面就全是裂图。
//
// 输出目录结构：
//
// <output>/
// db-<20060102-150405>.sql # pg_dump 全量导出（schema + data，可用 psql 恢复）
// images/<key> # R2 对象，保持原 key 路径
// images-manifest.json # key → 实际大小 / SHA-256 / GET 元数据
//
// 用法：TamaBox backup --output /var/backups/tamabox
//
// TamaBox backup --output . --db-only # 只备份数据库
// TamaBox backup --output . --images-only # 只备份图片
var Backup = &cli.Command{
Name: "backup",
Usage: "Back up the database and all R2 objects to a local directory",
Action: runBackup,
Flags: []cli.Flag{
&cli.StringFlag{
Name: "output",
Value: ".",
Usage: "Output directory for the backup files",
},
&cli.BoolFlag{
Name: "db-only",
Usage: "Only back up the database (skip R2 images)",
},
&cli.BoolFlag{
Name: "images-only",
Usage: "Only back up R2 images (skip the database)",
},
},
}
func runBackup(ctx *cli.Context) error {
if ctx.Bool("db-only") && ctx.Bool("images-only") {
return errors.New("--db-only and --images-only cannot be used together")
}
if err := conf.Init(); err != nil {
return errors.Wrap(err, "load configuration")
}
outDir := ctx.String("output")
if outDir == "" {
return errors.New("--output must not be empty")
}
if err := os.MkdirAll(outDir, 0o700); err != nil {
return errors.Wrapf(err, "create output directory %q", outDir)
}
dbOnly := ctx.Bool("db-only")
imagesOnly := ctx.Bool("images-only")
if !imagesOnly {
if err := backupDatabase(ctx.Context, outDir); err != nil {
return err
}
}
if !dbOnly {
if err := backupImages(ctx.Context, outDir); err != nil {
return err
}
}
logrus.WithField("dir", outDir).Info("备份完成")
return nil
}
// backupDatabase 用 pg_dump 导出 PostgreSQL 全量数据。
//
// 为什么用外部 pg_dump 而不是在进程内逐表 SELECT：pg_dump 输出的 .sql 是标准恢复格式，
// 直接用 psql 恢复，且能正确处理序列、外键、软删除行、大对象等进程内手写导出极易漏掉的
// 细节。项目实际使用 PostgreSQL（见 code-review-2026-08-28.md P1-4）。
func backupDatabase(ctx context.Context, outDir string) error {
if conf.Database.Type != "" && conf.Database.Type != "postgres" {
return errors.Errorf("备份当前仅支持 PostgreSQL，配置为 %q", conf.Database.Type)
}
pgDump, err := exec.LookPath("pg_dump")
if err != nil {
return errors.Wrap(err, "未找到 pg_dump（PostgreSQL 客户端工具），请安装 postgresql-client")
}
ts := time.Now().Format("20060102-150405")
outFile := filepath.Join(outDir, fmt.Sprintf("db-%s.sql", ts))
// 密码经环境变量传递，避免出现在进程参数里（ps 可见）。
cmd := exec.CommandContext(ctx, pgDump,
"--host", conf.Database.Host,
"--port", fmt.Sprintf("%d", conf.Database.Port),
"--username", conf.Database.User,
"--dbname", conf.Database.Name,
"--no-owner", "--no-privileges",
"--format", "plain",
)
cmd.Env = append(os.Environ(), "PGPASSWORD="+conf.Database.Password)
var dumpErr strings.Builder
if err := writeFileAtomically(outFile, func(w io.Writer) error {
cmd.Stdout = w
cmd.Stderr = &dumpErr
if err := cmd.Run(); err != nil {
return errors.Wrapf(err, "pg_dump failed: %s", strings.TrimSpace(dumpErr.String()))
}
return nil
}); err != nil {
return err
}
logrus.WithField("file", outFile).Info("数据库已备份")
return nil
}
// writeFileAtomically 保留数据库、manifest 与对象下载共用的原子写修复：
// 只有完整写入、Sync 并关闭成功后才替换目标，失败时清理临时 .part 文件。
func writeFileAtomically(outFile string, write func(io.Writer) error) error {
f, err := os.CreateTemp(filepath.Dir(outFile), "."+filepath.Base(outFile)+"-*.part")
if err != nil {
return errors.Wrapf(err, "create temporary file for %q", outFile)
}
tmpFile := f.Name()
defer os.Remove(tmpFile)
defer f.Close()
if err := write(f); err != nil {
return err
}
if err := f.Sync(); err != nil {
return errors.Wrapf(err, "sync temporary file for %q", outFile)
}
if err := f.Close(); err != nil {
return errors.Wrapf(err, "close temporary file for %q", outFile)
}
if err := os.Rename(tmpFile, outFile); err != nil {
return errors.Wrapf(err, "finalize %q", outFile)
}
return nil
}
// imageManifestEntry 记录实际下载内容的大小和 SHA-256，以及 GET 返回的原始元数据。
// ETag 只是服务商元数据，不能当作内容 MD5 或完整性校验的替代品。
type imageManifestEntry struct {
Key string `json:"key"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
ETag string `json:"etag,omitempty"`
ContentType string `json:"content_type,omitempty"`
CacheControl string `json:"cache_control,omitempty"`
}
type backupS3API interface {
ListObjectsV2(context.Context, *s3.ListObjectsV2Input, ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
GetObject(context.Context, *s3.GetObjectInput, ...func(*s3.Options)) (*s3.GetObjectOutput, error)
}
type backupDownloadPlan struct {
key string
destination string
}
type downloadedImageObject struct {
size int64
sha256 string
etag string
contentType string
cacheControl string
}
// backupImages 默认使用空前缀列举配置 bucket 的全部对象，而不是假定图片都在 tamabox/ 下。
func backupImages(ctx context.Context, outDir string) error {
client, err := backupS3Client(ctx)
if err != nil {
return errors.Wrap(err, "get R2 client for backup")
}
return backupImagesWithClient(ctx, client, conf.Upload.ImageBucket, outDir, "")
}
// backupImagesWithClient 允许测试和隔离演练显式指定 prefix。
// 所有分页 List、key 校验和本地路径预检都在第一次 GetObject 之前完成。
func backupImagesWithClient(ctx context.Context, client backupS3API, bucket, outDir, prefix string) error {
keys, err := listAllBackupKeys(ctx, client, bucket, prefix)
if err != nil {
return err
}
imageDir := filepath.Join(outDir, "images")
plans, err := planBackupDownloads(imageDir, keys)
if err != nil {
return err
}
manifest := make([]imageManifestEntry, 0, len(plans))
var totalBytes int64
for _, plan := range plans {
if err := ensureBackupDestinationDirectory(imageDir, plan.destination); err != nil {
return err
}
downloaded, err := downloadObject(ctx, client, bucket, plan.key, plan.destination)
if err != nil {
return err
}
manifest = append(manifest, imageManifestEntry{
Key: plan.key,
Size: downloaded.size,
SHA256: downloaded.sha256,
ETag: downloaded.etag,
ContentType: downloaded.contentType,
CacheControl: downloaded.cacheControl,
})
totalBytes += downloaded.size
}
manifestFile := filepath.Join(outDir, "images-manifest.json")
if err := writeFileAtomically(manifestFile, func(w io.Writer) error {
enc := json.NewEncoder(w)
enc.SetIndent("", " ")
if err := enc.Encode(manifest); err != nil {
return errors.Wrap(err, "write manifest")
}
return nil
}); err != nil {
return err
}
logrus.WithFields(logrus.Fields{
"objects": len(manifest),
"bytes": totalBytes,
"dir": imageDir,
"prefix": prefix,
}).Info("图片已备份")
return nil
}
func listAllBackupKeys(ctx context.Context, client backupS3API, bucket, prefix string) ([]string, error) {
keys := make([]string, 0)
var continuationToken *string
seenTokens := make(map[string]struct{})
for {
page, err := client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{
Bucket: aws.String(bucket),
Prefix: aws.String(prefix),
ContinuationToken: continuationToken,
})
if err != nil {
return nil, errors.Wrapf(err, "list R2 objects prefix %q", prefix)
}
if page == nil {
return nil, errors.New("list R2 objects returned a nil page")
}
for _, object := range page.Contents {
// nil key 与空 key 一样是无效输入；统一转成空串，由完整 List 后的预检拒绝。
keys = append(keys, aws.ToString(object.Key))
}
if !aws.ToBool(page.IsTruncated) {
return keys, nil
}
next := aws.ToString(page.NextContinuationToken)
if next == "" {
return nil, errors.New("truncated R2 list response has no continuation token")
}
if _, exists := seenTokens[next]; exists {
return nil, errors.Errorf("R2 list continuation token %q repeated", next)
}
seenTokens[next] = struct{}{}
continuationToken = aws.String(next)
}
}
func planBackupDownloads(imageDir string, keys []string) ([]backupDownloadPlan, error) {
plans := make([]backupDownloadPlan, 0, len(keys))
files := make(map[string]string, len(keys))
directories := make(map[string]string)
root, err := filepath.Abs(imageDir)
if err != nil {
return nil, errors.Wrap(err, "resolve images directory")
}
directories[canonicalLocalPath(root)] = ""
for _, key := range keys {
destination, err := localImagePath(root, key)
if err != nil {
return nil, err
}
canonicalDestination := canonicalLocalPath(destination)
if previous, exists := files[canonicalDestination]; exists {
return nil, errors.Errorf("objects %q and %q map to the same local file", previous, key)
}
if previous, exists := directories[canonicalDestination]; exists {
return nil, errors.Errorf("file/directory collision between objects %q and %q", previous, key)
}
for parent := filepath.Dir(destination); pathWithinDirectory(root, parent); parent = filepath.Dir(parent) {
canonicalParent := canonicalLocalPath(parent)
if previous, exists := files[canonicalParent]; exists {
return nil, errors.Errorf("file/directory collision between objects %q and %q", previous, key)
}
if _, exists := directories[canonicalParent]; !exists {
directories[canonicalParent] = key
}
if parent == root {
break
}
}
files[canonicalDestination] = key
plans = append(plans, backupDownloadPlan{key: key, destination: destination})
}
if err := prepareBackupImageRoot(root); err != nil {
return nil, err
}
for _, plan := range plans {
if err := preflightBackupLocalPath(root, plan.destination); err != nil {
return nil, err
}
}
return plans, nil
}
func validateObjectKey(key string) error {
if key == "" {
return errors.New("R2 object key must not be empty")
}
if strings.ContainsRune(key, 0) {
return errors.Errorf("R2 object key %q contains NUL", key)
}
if strings.Contains(key, `\`) {
return errors.Errorf("R2 object key %q contains a backslash", key)
}
if strings.HasSuffix(key, "/") {
return errors.Errorf("R2 object key %q is a directory key", key)
}
if strings.HasPrefix(key, "/") || filepath.IsAbs(filepath.FromSlash(key)) || filepath.VolumeName(filepath.FromSlash(key)) != "" ||
(len(key) >= 2 && ((key[0] >= 'A' && key[0] <= 'Z') || (key[0] >= 'a' && key[0] <= 'z')) && key[1] == ':') {
return errors.Errorf("R2 object key %q is an absolute or volume-qualified path", key)
}
for _, segment := range strings.Split(key, "/") {
if segment == "" || segment == "." || segment == ".." {
return errors.Errorf("R2 object key %q contains an empty or dot path segment", key)
}
}
return nil
}
func localImagePath(imageDir, key string) (string, error) {
if err := validateObjectKey(key); err != nil {
return "", err
}
root, err := filepath.Abs(imageDir)
if err != nil {
return "", errors.Wrap(err, "resolve images directory")
}
destination := filepath.Join(root, filepath.FromSlash(key))
if !pathWithinDirectory(root, destination) || destination == root {
return "", errors.Errorf("R2 object key %q escapes the images directory", key)
}
return destination, nil
}
func pathWithinDirectory(root, candidate string) bool {
rel, err := filepath.Rel(root, candidate)
if err != nil || filepath.IsAbs(rel) {
return false
}
return rel == "." || rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator))
}
func canonicalLocalPath(path string) string {
cleaned := filepath.Clean(path)
if runtime.GOOS == "windows" {
return strings.ToLower(cleaned)
}
return cleaned
}
func prepareBackupImageRoot(imageDir string) error {
info, err := os.Lstat(imageDir)
if os.IsNotExist(err) {
if err := os.MkdirAll(imageDir, 0o700); err != nil {
return errors.Wrap(err, "create images directory")
}
info, err = os.Lstat(imageDir)
}
if err != nil {
return errors.Wrap(err, "inspect images directory")
}
if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
return errors.Errorf("images path %q must be a real directory, not a symlink or file", imageDir)
}
return nil
}
func preflightBackupLocalPath(imageDir, destination string) error {
info, err := os.Lstat(destination)
if err == nil && (info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular()) {
return errors.Errorf("backup destination %q is not a regular file", destination)
}
if err != nil && !os.IsNotExist(err) {
return errors.Wrapf(err, "inspect backup destination %q", destination)
}
for parent := filepath.Dir(destination); parent != imageDir; parent = filepath.Dir(parent) {
if !pathWithinDirectory(imageDir, parent) {
return errors.Errorf("backup destination %q escapes images directory", destination)
}
info, err := os.Lstat(parent)
if os.IsNotExist(err) {
continue
}
if err != nil {
return errors.Wrapf(err, "inspect backup parent %q", parent)
}
if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
return errors.Errorf("backup parent %q is not a real directory", parent)
}
}
return nil
}
func ensureBackupDestinationDirectory(imageDir, destination string) error {
root, err := filepath.Abs(imageDir)
if err != nil {
return err
}
parent := filepath.Dir(destination)
rel, err := filepath.Rel(root, parent)
if err != nil || !pathWithinDirectory(root, parent) {
return errors.Errorf("invalid backup destination %q", destination)
}
if rel == "." {
return nil
}
current := root
for _, segment := range strings.Split(rel, string(filepath.Separator)) {
current = filepath.Join(current, segment)
info, err := os.Lstat(current)
if os.IsNotExist(err) {
if err := os.Mkdir(current, 0o700); err != nil && !os.IsExist(err) {
return errors.Wrapf(err, "create backup directory %q", current)
}
info, err = os.Lstat(current)
}
if err != nil {
return errors.Wrapf(err, "inspect backup directory %q", current)
}
if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
return errors.Errorf("backup parent %q is not a real directory", current)
}
}
return nil
}
// backupS3Client 与上传、恢复共用 storage.NewS3Client 的 endpoint 语义：
// endpoint 可不带路径或只带 /<bucket>，请求始终以 Bucket 参数和原始完整 key 寻址。
// List 返回什么 key 就下载什么 key，不额外添加或剥离 bucket 前缀。
func backupS3Client(ctx context.Context) (*s3.Client, error) {
return storage.NewS3Client(
ctx,
conf.Upload.ImageEndpoint,
conf.Upload.ImageBucket,
conf.Upload.ImageAccessID,
conf.Upload.ImageAccessSecret,
)
}
// downloadObject 原子下载单个对象，并返回实际落盘内容的 SHA-256 和 GET 元数据。
// 每次尝试都有独立 60 秒 context；流中断会从头重试整个对象，最多 3 次。
func downloadObject(ctx context.Context, client backupS3API, bucket, key, destination string) (downloadedImageObject, error) {
var lastErr error
for attempt := 0; attempt < imageObjectMaxAttempts; attempt++ {
if err := ctx.Err(); err != nil {
return downloadedImageObject{}, err
}
attemptCtx, cancel := context.WithTimeout(ctx, imageObjectAttemptTimeout)
downloaded, err := downloadObjectOnce(attemptCtx, client, bucket, key, destination)
cancel()
if err == nil {
return downloaded, nil
}
lastErr = err
if ctx.Err() != nil {
return downloadedImageObject{}, ctx.Err()
}
if attempt == imageObjectMaxAttempts-1 {
break
}
if err := waitForImageObjectRetry(ctx, imageObjectRetryBackoff<<attempt); err != nil {
return downloadedImageObject{}, err
}
}
return downloadedImageObject{}, errors.Wrapf(lastErr, "download %q after %d attempts", key, imageObjectMaxAttempts)
}
func downloadObjectOnce(ctx context.Context, client backupS3API, bucket, key, destination string) (downloadedImageObject, error) {
out, err := client.GetObject(ctx, &s3.GetObjectInput{
Bucket: aws.String(bucket),
Key: aws.String(key),
})
if err != nil {
return downloadedImageObject{}, errors.Wrapf(err, "get R2 object %q", key)
}
if out == nil || out.Body == nil {
return downloadedImageObject{}, errors.Errorf("get R2 object %q returned an empty response body", key)
}
hash := sha256.New()
var size int64
writeErr := writeFileAtomically(destination, func(w io.Writer) error {
var err error
size, err = io.Copy(io.MultiWriter(w, hash), out.Body)
if err != nil {
return errors.Wrapf(err, "download %q", key)
}
if out.ContentLength != nil && size != aws.ToInt64(out.ContentLength) {
return errors.Wrapf(io.ErrUnexpectedEOF, "download %q: GET content length is %d, received %d", key, aws.ToInt64(out.ContentLength), size)
}
return nil
})
_ = out.Body.Close()
if writeErr != nil {
return downloadedImageObject{}, writeErr
}
return downloadedImageObject{
size: size,
sha256: hex.EncodeToString(hash.Sum(nil)),
etag: aws.ToString(out.ETag),
contentType: aws.ToString(out.ContentType),
cacheControl: aws.ToString(out.CacheControl),
}, nil
}
func waitForImageObjectRetry(ctx context.Context, delay time.Duration) error {
timer := time.NewTimer(delay)
defer timer.Stop()
select {
case <-ctx.Done():
return ctx.Err()
case <-timer.C:
return nil
}
}
internal/cmd/backup_restore.go
-437
View File
@@ -1,437 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"bytes"
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go"
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
"github.com/urfave/cli/v2"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/storage"
)
const maxImageManifestBytes = 64 << 20 // 64 MiB，足以容纳大量对象且避免恶意清单耗尽内存。
// RestoreImages 从 backup 生成的 images-manifest.json 和 images/ 恢复 R2 对象。
var RestoreImages = &cli.Command{
Name: "restore-images",
Usage: "Validate and restore backed-up images to R2",
Action: runRestoreImages,
Flags: []cli.Flag{
&cli.StringFlag{
Name: "input",
Required: true,
Usage: "Backup directory or images-manifest.json path",
},
&cli.BoolFlag{
Name: "dry-run",
Usage: "Validate local files and remote targets without writing objects",
},
&cli.BoolFlag{
Name: "yes",
Usage: "Confirm actual remote writes",
},
&cli.BoolFlag{
Name: "overwrite",
Usage: "Allow replacing objects that already exist",
},
&cli.StringFlag{
Name: "target-prefix",
Value: "",
Usage: "Prefix prepended to every restored key (for isolated drills)",
},
},
}
type restoreImagesOptions struct {
Input string
DryRun bool
Yes bool
Overwrite bool
TargetPrefix string
}
// restoreObjectStore 的 PutObject 是带重试的高层操作，便于离线 fake 精确断言零写入。
type restoreObjectStore interface {
HeadObject(context.Context, *s3.HeadObjectInput, ...func(*s3.Options)) (*s3.HeadObjectOutput, error)
PutObject(context.Context, *s3.PutObjectInput) error
}
type r2RestoreObjectStore struct {
client *s3.Client
}
func (s *r2RestoreObjectStore) HeadObject(ctx context.Context, input *s3.HeadObjectInput, options ...func(*s3.Options)) (*s3.HeadObjectOutput, error) {
return s.client.HeadObject(ctx, input, options...)
}
func (s *r2RestoreObjectStore) PutObject(ctx context.Context, input *s3.PutObjectInput) error {
// storage.PutObject 提供每次独立 60 秒超时、最多 3 次重试、Body 回绕和可取消退避。
return storage.PutObject(ctx, s.client, input)
}
type restorePlannedObject struct {
entry imageManifestEntry
sourcePath string
targetKey string
}
func runRestoreImages(ctx *cli.Context) error {
opts := restoreImagesOptions{
Input: ctx.String("input"),
DryRun: ctx.Bool("dry-run"),
Yes: ctx.Bool("yes"),
Overwrite: ctx.Bool("overwrite"),
TargetPrefix: ctx.String("target-prefix"),
}
if opts.Input == "" {
return errors.New("--input must not be empty")
}
if !opts.DryRun && !opts.Yes {
return errors.New("actual restore writes require --yes (or use --dry-run)")
}
if err := conf.Init(); err != nil {
return errors.Wrap(err, "load configuration")
}
client, err := backupS3Client(ctx.Context)
if err != nil {
return errors.Wrap(err, "get R2 client for image restore")
}
return restoreImagesWithStore(ctx.Context, &r2RestoreObjectStore{client: client}, conf.Upload.ImageBucket, opts)
}
func restoreImagesWithStore(ctx context.Context, store restoreObjectStore, bucket string, opts restoreImagesOptions) error {
if opts.Input == "" {
return errors.New("restore input must not be empty")
}
if !opts.DryRun && !opts.Yes {
return errors.New("actual restore writes require --yes (or use --dry-run)")
}
manifestPath, imageDir, err := resolveRestoreInput(opts.Input)
if err != nil {
return err
}
entries, err := readImageManifest(manifestPath)
if err != nil {
return err
}
// 关键安全顺序：先验证所有 manifest 条目和全部本地文件，再做任何 Head/Put。
// 因此重复 key、非法 hash/size、缺文件、篡改或 symlink 都不会造成部分上传。
objects := make([]restorePlannedObject, 0, len(entries))
for _, entry := range entries {
targetKey, err := restoreTargetKey(opts.TargetPrefix, entry.Key)
if err != nil {
return err
}
sourcePath, err := localImagePath(imageDir, entry.Key)
if err != nil {
return err
}
if err := validateRestoreLocalFile(imageDir, sourcePath, entry); err != nil {
return err
}
objects = append(objects, restorePlannedObject{
entry: entry,
sourcePath: sourcePath,
targetKey: targetKey,
})
}
// 默认先 Head 所有目标。任何目标已存在都会在 Put 循环开始前失败，保证零 Put。
if !opts.Overwrite {
for _, object := range objects {
headCtx, cancel := context.WithTimeout(ctx, imageObjectAttemptTimeout)
_, err := store.HeadObject(headCtx, &s3.HeadObjectInput{
Bucket: aws.String(bucket),
Key: aws.String(object.targetKey),
})
cancel()
if err == nil {
return errors.Errorf("restore target %q already exists; no objects were uploaded (use --overwrite to replace)", object.targetKey)
}
if !isS3ObjectNotFound(err) {
return errors.Wrapf(err, "check restore target %q; no objects were uploaded", object.targetKey)
}
}
}
if opts.DryRun {
logrus.WithFields(logrus.Fields{
"objects": len(objects),
"prefix": opts.TargetPrefix,
}).Info("图片恢复演练完成，未写入对象")
return nil
}
succeeded := 0
for _, object := range objects {
file, err := openRestoreFileForPut(object.sourcePath, object.entry.Size)
if err != nil {
return errors.Wrapf(err, "open validated restore file for %q after %d successful uploads; restore is not transactional", object.entry.Key, succeeded)
}
input := &s3.PutObjectInput{
Bucket: aws.String(bucket),
Key: aws.String(object.targetKey),
Body: file,
ContentLength: aws.Int64(object.entry.Size),
ContentType: nonEmptyStringPointer(object.entry.ContentType),
CacheControl: nonEmptyStringPointer(object.entry.CacheControl),
}
putErr := store.PutObject(ctx, input)
closeErr := file.Close()
if putErr != nil {
return errors.Wrapf(putErr, "restore object %q to %q failed after %d successful uploads; restore is not transactional", object.entry.Key, object.targetKey, succeeded)
}
if closeErr != nil {
return errors.Wrapf(closeErr, "close restored file %q (remote object was uploaded); restore is not transactional", object.sourcePath)
}
succeeded++
}
logrus.WithFields(logrus.Fields{
"objects": succeeded,
"prefix": opts.TargetPrefix,
}).Info("图片恢复完成")
return nil
}
func resolveRestoreInput(input string) (manifestPath, imageDir string, err error) {
info, err := os.Lstat(input)
if err != nil {
return "", "", errors.Wrapf(err, "inspect restore input %q", input)
}
if info.Mode()&os.ModeSymlink != 0 {
return "", "", errors.Errorf("restore input %q must not be a symlink", input)
}
manifestPath = input
if info.IsDir() {
manifestPath = filepath.Join(input, "images-manifest.json")
} else if !info.Mode().IsRegular() {
return "", "", errors.Errorf("restore input %q is neither a directory nor a regular manifest file", input)
}
return manifestPath, filepath.Join(filepath.Dir(manifestPath), "images"), nil
}
func readImageManifest(manifestPath string) ([]imageManifestEntry, error) {
info, err := os.Lstat(manifestPath)
if err != nil {
return nil, errors.Wrapf(err, "inspect image manifest %q", manifestPath)
}
if info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular() {
return nil, errors.Errorf("image manifest %q must be a regular non-symlink file", manifestPath)
}
if info.Size() > maxImageManifestBytes {
return nil, errors.Errorf("image manifest %q exceeds the %d-byte limit", manifestPath, maxImageManifestBytes)
}
file, err := os.Open(manifestPath)
if err != nil {
return nil, errors.Wrapf(err, "open image manifest %q", manifestPath)
}
data, readErr := io.ReadAll(io.LimitReader(file, maxImageManifestBytes+1))
closeErr := file.Close()
if readErr != nil {
return nil, errors.Wrap(readErr, "read image manifest")
}
if closeErr != nil {
return nil, errors.Wrap(closeErr, "close image manifest")
}
if len(data) > maxImageManifestBytes {
return nil, errors.Errorf("image manifest %q exceeds the %d-byte limit", manifestPath, maxImageManifestBytes)
}
decoder := json.NewDecoder(bytes.NewReader(data))
var entries []imageManifestEntry
if err := decoder.Decode(&entries); err != nil {
return nil, errors.Wrap(err, "decode image manifest")
}
if entries == nil {
return nil, errors.New("image manifest must be a JSON array, not null")
}
var trailing json.RawMessage
if err := decoder.Decode(&trailing); err != io.EOF {
if err == nil {
return nil, errors.New("image manifest contains trailing JSON")
}
return nil, errors.Wrap(err, "image manifest contains trailing data")
}
seen := make(map[string]struct{}, len(entries))
for index := range entries {
entry := &entries[index]
if err := validateObjectKey(entry.Key); err != nil {
return nil, errors.Wrapf(err, "invalid manifest entry %d", index)
}
if _, exists := seen[entry.Key]; exists {
return nil, errors.Errorf("image manifest contains duplicate key %q", entry.Key)
}
seen[entry.Key] = struct{}{}
if entry.Size < 0 {
return nil, errors.Errorf("manifest entry %q has negative size %d", entry.Key, entry.Size)
}
decodedHash, err := hex.DecodeString(entry.SHA256)
if err != nil || len(decodedHash) != sha256.Size {
return nil, errors.Errorf("manifest entry %q has invalid SHA-256 %q", entry.Key, entry.SHA256)
}
entry.SHA256 = strings.ToLower(entry.SHA256)
}
return entries, nil
}
func restoreTargetKey(prefix, key string) (string, error) {
if prefix != "" && !strings.HasSuffix(prefix, "/") {
prefix += "/"
}
target := prefix + key
if err := validateObjectKey(target); err != nil {
return "", errors.Wrapf(err, "invalid restore target for source key %q", key)
}
return target, nil
}
func validateRestoreLocalFile(imageDir, sourcePath string, entry imageManifestEntry) error {
root, err := filepath.Abs(imageDir)
if err != nil {
return err
}
if err := validateRestoreDirectoryChain(root, filepath.Dir(sourcePath)); err != nil {
return err
}
info, err := os.Lstat(sourcePath)
if err != nil {
return errors.Wrapf(err, "inspect local image for %q", entry.Key)
}
if info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular() {
return errors.Errorf("local image for %q must be a regular non-symlink file", entry.Key)
}
if info.Size() != entry.Size {
return errors.Errorf("local image size mismatch for %q: manifest=%d actual=%d", entry.Key, entry.Size, info.Size())
}
file, err := os.Open(sourcePath)
if err != nil {
return errors.Wrapf(err, "open local image for %q", entry.Key)
}
openedInfo, statErr := file.Stat()
if statErr != nil {
_ = file.Close()
return errors.Wrapf(statErr, "stat opened local image for %q", entry.Key)
}
if !openedInfo.Mode().IsRegular() || openedInfo.Size() != entry.Size {
_ = file.Close()
return errors.Errorf("opened local image for %q is not the expected regular file", entry.Key)
}
hash := sha256.New()
_, hashErr := io.Copy(hash, file)
closeErr := file.Close()
if hashErr != nil {
return errors.Wrapf(hashErr, "hash local image for %q", entry.Key)
}
if closeErr != nil {
return errors.Wrapf(closeErr, "close local image for %q", entry.Key)
}
actualHash := hex.EncodeToString(hash.Sum(nil))
if actualHash != entry.SHA256 {
return errors.Errorf("local image SHA-256 mismatch for %q: manifest=%s actual=%s", entry.Key, entry.SHA256, actualHash)
}
return nil
}
func validateRestoreDirectoryChain(root, parent string) error {
rootInfo, err := os.Lstat(root)
if err != nil {
return errors.Wrapf(err, "inspect restore images directory %q", root)
}
if rootInfo.Mode()&os.ModeSymlink != 0 || !rootInfo.IsDir() {
return errors.Errorf("restore images path %q must be a real directory", root)
}
rel, err := filepath.Rel(root, parent)
if err != nil || !pathWithinDirectory(root, parent) {
return errors.Errorf("restore file parent %q escapes images directory", parent)
}
if rel == "." {
return nil
}
current := root
for _, segment := range strings.Split(rel, string(filepath.Separator)) {
current = filepath.Join(current, segment)
info, err := os.Lstat(current)
if err != nil {
return errors.Wrapf(err, "inspect restore parent directory %q", current)
}
if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
return errors.Errorf("restore parent %q must be a real directory", current)
}
}
return nil
}
func openRestoreFileForPut(sourcePath string, expectedSize int64) (*os.File, error) {
info, err := os.Lstat(sourcePath)
if err != nil {
return nil, err
}
if info.Mode()&os.ModeSymlink != 0 || !info.Mode().IsRegular() || info.Size() != expectedSize {
return nil, fmt.Errorf("local file %q changed after validation", sourcePath)
}
file, err := os.Open(sourcePath)
if err != nil {
return nil, err
}
openedInfo, err := file.Stat()
if err != nil {
_ = file.Close()
return nil, err
}
if !openedInfo.Mode().IsRegular() || openedInfo.Size() != expectedSize {
_ = file.Close()
return nil, fmt.Errorf("local file %q changed after validation", sourcePath)
}
return file, nil
}
func isS3ObjectNotFound(err error) bool {
if err == nil {
return false
}
var statusErr interface{ HTTPStatusCode() int }
if errors.As(err, &statusErr) && statusErr.HTTPStatusCode() == 404 {
return true
}
var apiErr smithy.APIError
if errors.As(err, &apiErr) {
switch apiErr.ErrorCode() {
case "NotFound", "NoSuchKey", "404":
return true
}
}
return false
}
func nonEmptyStringPointer(value string) *string {
if value == "" {
return nil
}
return aws.String(value)
}
internal/cmd/backup_restore_integration_test.go
-184
View File
@@ -1,184 +0,0 @@
package cmd
import (
"bytes"
"context"
"crypto/rand"
"crypto/sha256"
"encoding/hex"
"fmt"
"io"
"os"
"testing"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/stretchr/testify/require"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/storage"
)
// TestR2BackupRestoreIntegration 默认跳过。只有显式设置 TB_R2_INTEGRATION=1，
// 并通过 NEKOBOX_CONFIG_PATH 提供真实 R2 配置时才运行。
// 测试只访问 tamabox-backup-test/<随机>/ 下的 source/ 与 target/ 两个专属前缀，
// 绝不执行全桶 List，也不会读取、覆盖或删除其他 key。
func TestR2BackupRestoreIntegration(t *testing.T) {
if os.Getenv("TB_R2_INTEGRATION") != "1" {
t.Skip("set TB_R2_INTEGRATION=1 to run the real R2 integration test")
}
if os.Getenv("NEKOBOX_CONFIG_PATH") == "" {
t.Fatal("NEKOBOX_CONFIG_PATH must point to the R2 integration configuration")
}
require.NoError(t, conf.Init())
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()
client, err := storage.NewS3Client(
ctx,
conf.Upload.ImageEndpoint,
conf.Upload.ImageBucket,
conf.Upload.ImageAccessID,
conf.Upload.ImageAccessSecret,
)
require.NoError(t, err)
random := make([]byte, 12)
_, err = rand.Read(random)
require.NoError(t, err)
basePrefix := fmt.Sprintf("tamabox-backup-test/%d-%s/", time.Now().UTC().UnixNano(), hex.EncodeToString(random))
sourcePrefix := basePrefix + "source/"
targetPrefix := basePrefix + "target/"
objects := []struct {
relativeKey string
body []byte
contentType string
cacheControl string
}{
{
relativeKey: "2026/11/04/root.webp",
body: []byte("tamabox-r2-integration-root"),
contentType: "image/webp",
cacheControl: "public, max-age=60",
},
{
relativeKey: "picture/2026/11/04/picture.webp",
body: []byte("tamabox-r2-integration-picture"),
contentType: "image/webp",
cacheControl: "public, max-age=120",
},
}
// created 只记录本测试成功创建的精确 key。任何失败清理也只删除这些 key。
created := make(map[string]bool)
t.Cleanup(func() {
cleanupCtx, cleanupCancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cleanupCancel()
for key := range created {
if err := storage.DeleteObject(cleanupCtx, client, conf.Upload.ImageBucket, key); err != nil {
t.Errorf("clean up own R2 key %q: %v", key, err)
}
}
})
for _, object := range objects {
key := sourcePrefix + object.relativeKey
err := storage.PutObject(ctx, client, &s3.PutObjectInput{
Bucket: aws.String(conf.Upload.ImageBucket),
Key: aws.String(key),
Body: bytes.NewReader(object.body),
ContentLength: aws.Int64(int64(len(object.body))),
ContentType: aws.String(object.contentType),
CacheControl: aws.String(object.cacheControl),
})
require.NoError(t, err)
created[key] = true
}
backupDir := t.TempDir()
require.NoError(t, backupImagesWithClient(ctx, client, conf.Upload.ImageBucket, backupDir, sourcePrefix))
manifest, err := readImageManifest(backupDir + string(os.PathSeparator) + "images-manifest.json")
require.NoError(t, err)
require.Len(t, manifest, len(objects))
manifestKeys := make(map[string]bool, len(manifest))
for _, entry := range manifest {
manifestKeys[entry.Key] = true
}
for _, object := range objects {
require.True(t, manifestKeys[sourcePrefix+object.relativeKey])
}
for _, object := range objects {
sourceKey := sourcePrefix + object.relativeKey
require.NoError(t, storage.DeleteObject(ctx, client, conf.Upload.ImageBucket, sourceKey))
delete(created, sourceKey)
}
store := &integrationTrackingRestoreStore{
base: &r2RestoreObjectStore{client: client},
onUpload: func(key string) {
created[key] = true
},
}
require.NoError(t, restoreImagesWithStore(ctx, store, conf.Upload.ImageBucket, restoreImagesOptions{
Input: backupDir,
Yes: true,
TargetPrefix: targetPrefix,
}))
for _, object := range objects {
targetKey := targetPrefix + sourcePrefix + object.relativeKey
require.True(t, created[targetKey], "restore must report its own successful Put")
output, err := client.GetObject(ctx, &s3.GetObjectInput{
Bucket: aws.String(conf.Upload.ImageBucket),
Key: aws.String(targetKey),
})
require.NoError(t, err)
body, readErr := io.ReadAll(output.Body)
closeErr := output.Body.Close()
require.NoError(t, readErr)
require.NoError(t, closeErr)
digest := sha256.Sum256(object.body)
require.Equal(t, fmt.Sprintf("%x", digest), fmt.Sprintf("%x", sha256.Sum256(body)))
require.Equal(t, object.contentType, aws.ToString(output.ContentType))
require.Equal(t, object.cacheControl, aws.ToString(output.CacheControl))
}
for key := range created {
require.NoError(t, storage.DeleteObject(ctx, client, conf.Upload.ImageBucket, key))
delete(created, key)
}
requireOwnPrefixEmpty(ctx, t, client, conf.Upload.ImageBucket, sourcePrefix)
requireOwnPrefixEmpty(ctx, t, client, conf.Upload.ImageBucket, targetPrefix)
}
type integrationTrackingRestoreStore struct {
base restoreObjectStore
onUpload func(string)
}
func (s *integrationTrackingRestoreStore) HeadObject(ctx context.Context, input *s3.HeadObjectInput, options ...func(*s3.Options)) (*s3.HeadObjectOutput, error) {
return s.base.HeadObject(ctx, input, options...)
}
func (s *integrationTrackingRestoreStore) PutObject(ctx context.Context, input *s3.PutObjectInput) error {
if err := s.base.PutObject(ctx, input); err != nil {
return err
}
s.onUpload(aws.ToString(input.Key))
return nil
}
func requireOwnPrefixEmpty(ctx context.Context, t *testing.T, client *s3.Client, bucket, prefix string) {
t.Helper()
require.NotEmpty(t, prefix)
output, err := client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{
Bucket: aws.String(bucket),
Prefix: aws.String(prefix),
})
require.NoError(t, err)
require.Empty(t, output.Contents, "专属 prefix 清理后必须为空：%q", prefix)
require.False(t, aws.ToBool(output.IsTruncated), "随机专属 prefix 下对象数不应触发分页")
}
internal/cmd/backup_restore_test.go
-603
View File
@@ -1,603 +0,0 @@
package cmd
import (
"context"
"crypto/sha256"
"encoding/json"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"testing"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/aws-sdk-go-v2/service/s3/types"
"github.com/stretchr/testify/require"
)
type fakeBackupObject struct {
body []byte
etag string
contentType string
cacheControl string
interruptedAttempts int
wrongLengthAttempts int
}
type fakeBackupS3 struct {
pages []*s3.ListObjectsV2Output
listInputs []*s3.ListObjectsV2Input
objects map[string]fakeBackupObject
getCalls map[string]int
getOrder []string
}
func (f *fakeBackupS3) ListObjectsV2(_ context.Context, input *s3.ListObjectsV2Input, _ ...func(*s3.Options)) (*s3.ListObjectsV2Output, error) {
f.listInputs = append(f.listInputs, input)
index := len(f.listInputs) - 1
if index >= len(f.pages) {
return nil, fmt.Errorf("unexpected ListObjectsV2 call %d", index+1)
}
return f.pages[index], nil
}
func (f *fakeBackupS3) GetObject(_ context.Context, input *s3.GetObjectInput, _ ...func(*s3.Options)) (*s3.GetObjectOutput, error) {
key := aws.ToString(input.Key)
if f.getCalls == nil {
f.getCalls = make(map[string]int)
}
f.getCalls[key]++
f.getOrder = append(f.getOrder, key)
object, exists := f.objects[key]
if !exists {
return nil, fmt.Errorf("unexpected GetObject key %q", key)
}
var body io.ReadCloser
if f.getCalls[key] <= object.interruptedAttempts {
body = io.NopCloser(&interruptedReader{data: append([]byte(nil), object.body...)})
} else {
body = io.NopCloser(strings.NewReader(string(object.body)))
}
contentLength := int64(len(object.body))
if f.getCalls[key] <= object.wrongLengthAttempts {
contentLength++
}
return &s3.GetObjectOutput{
Body: body,
ContentLength: aws.Int64(contentLength),
ETag: aws.String(object.etag),
ContentType: aws.String(object.contentType),
CacheControl: aws.String(object.cacheControl),
}, nil
}
type interruptedReader struct {
data []byte
}
func (r *interruptedReader) Read(p []byte) (int, error) {
if len(r.data) == 0 {
return 0, io.ErrUnexpectedEOF
}
n := copy(p, r.data)
r.data = r.data[n:]
if len(r.data) == 0 {
return n, io.ErrUnexpectedEOF
}
return n, nil
}
func backupListPage(keys []string, truncated bool, nextToken string) *s3.ListObjectsV2Output {
objects := make([]types.Object, 0, len(keys))
for _, key := range keys {
objects = append(objects, types.Object{
Key: aws.String(key),
Size: aws.Int64(999999), // 故意不可信；manifest 必须记录实际下载字节数。
ETag: aws.String("list-etag-must-not-be-used"),
})
}
output := &s3.ListObjectsV2Output{Contents: objects, IsTruncated: aws.Bool(truncated)}
if nextToken != "" {
output.NextContinuationToken = aws.String(nextToken)
}
return output
}
func TestBackupImagesWithClientCoversAllKeysAndPages(t *testing.T) {
keys := []string{
"2026/11/04/root.webp",
"picture/2026/11/04/picture.webp",
"tamabox/2025/12/historical.jpg",
"static/site.css",
}
objects := make(map[string]fakeBackupObject, len(keys))
for index, key := range keys {
objects[key] = fakeBackupObject{
body: []byte(fmt.Sprintf("actual-body-%d", index)),
etag: fmt.Sprintf("get-etag-%d", index),
contentType: []string{"image/webp", "image/webp", "image/jpeg", "text/css"}[index],
cacheControl: fmt.Sprintf("public, max-age=%d", index+60),
}
}
client := &fakeBackupS3{
pages: []*s3.ListObjectsV2Output{
backupListPage(keys[:2], true, "page-2"),
backupListPage(keys[2:], false, ""),
},
objects: objects,
}
outDir := t.TempDir()
require.NoError(t, backupImagesWithClient(context.Background(), client, "configured-bucket", outDir, ""))
require.Len(t, client.listInputs, 2)
for index, input := range client.listInputs {
require.Equal(t, "configured-bucket", aws.ToString(input.Bucket))
require.Equal(t, "", aws.ToString(input.Prefix), "生产默认必须列举整个 bucket")
if index == 0 {
require.Nil(t, input.ContinuationToken)
} else {
require.Equal(t, "page-2", aws.ToString(input.ContinuationToken))
}
}
require.ElementsMatch(t, keys, client.getOrder)
manifestBytes, err := os.ReadFile(filepath.Join(outDir, "images-manifest.json"))
require.NoError(t, err)
var manifest []imageManifestEntry
require.NoError(t, json.Unmarshal(manifestBytes, &manifest))
require.Len(t, manifest, len(keys))
for index, entry := range manifest {
require.Equal(t, keys[index], entry.Key)
object := objects[entry.Key]
require.Equal(t, int64(len(object.body)), entry.Size)
digest := sha256.Sum256(object.body)
require.Equal(t, fmt.Sprintf("%x", digest), entry.SHA256)
require.Equal(t, object.etag, entry.ETag)
require.Equal(t, object.contentType, entry.ContentType)
require.Equal(t, object.cacheControl, entry.CacheControl)
path, err := localImagePath(filepath.Join(outDir, "images"), entry.Key)
require.NoError(t, err)
content, err := os.ReadFile(path)
require.NoError(t, err)
require.Equal(t, object.body, content)
}
}
func TestBackupImagesWithClientSupportsIsolatedPrefixAndEmptyManifest(t *testing.T) {
t.Run("prefix", func(t *testing.T) {
key := "tamabox-backup-test/unit/source/root.webp"
client := &fakeBackupS3{
pages: []*s3.ListObjectsV2Output{backupListPage([]string{key}, false, "")},
objects: map[string]fakeBackupObject{
key: {body: []byte("isolated"), contentType: "image/webp"},
},
}
require.NoError(t, backupImagesWithClient(context.Background(), client, "bucket", t.TempDir(), "tamabox-backup-test/unit/source/"))
require.Len(t, client.listInputs, 1)
require.Equal(t, "tamabox-backup-test/unit/source/", aws.ToString(client.listInputs[0].Prefix))
require.Equal(t, []string{key}, client.getOrder)
})
t.Run("empty array", func(t *testing.T) {
client := &fakeBackupS3{pages: []*s3.ListObjectsV2Output{backupListPage(nil, false, "")}}
outDir := t.TempDir()
require.NoError(t, backupImagesWithClient(context.Background(), client, "bucket", outDir, ""))
content, err := os.ReadFile(filepath.Join(outDir, "images-manifest.json"))
require.NoError(t, err)
require.Equal(t, "[]", strings.TrimSpace(string(content)))
})
}
func TestBackupRejectsPathAttacksBeforeAnyDownload(t *testing.T) {
tests := []struct {
name string
key *string
}{
{name: "nil key", key: nil},
{name: "empty key", key: aws.String("")},
{name: "absolute POSIX", key: aws.String("/outside")},
{name: "absolute Windows", key: aws.String("C:/outside")},
{name: "volume relative", key: aws.String("C:outside")},
{name: "parent", key: aws.String("../outside")},
{name: "nested parent", key: aws.String("picture/../outside")},
{name: "backslash", key: aws.String(`picture\outside`)},
{name: "NUL", key: aws.String("picture/\x00outside")},
{name: "empty segment", key: aws.String("picture//outside")},
{name: "leading dot segment", key: aws.String("./outside")},
{name: "inner dot segment", key: aws.String("picture/./outside")},
{name: "directory", key: aws.String("picture/")},
{name: "dot only", key: aws.String(".")},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
page := backupListPage(nil, false, "")
page.Contents = []types.Object{{Key: tt.key}}
client := &fakeBackupS3{pages: []*s3.ListObjectsV2Output{page}}
err := backupImagesWithClient(context.Background(), client, "bucket", t.TempDir(), "")
require.Error(t, err)
require.Empty(t, client.getOrder, "非法 key 必须在任何下载前被拒绝")
})
}
}
func TestBackupPreflightsAllPagesAndLocalCollisionsBeforeDownload(t *testing.T) {
t.Run("invalid key on later page", func(t *testing.T) {
client := &fakeBackupS3{
pages: []*s3.ListObjectsV2Output{
backupListPage([]string{"picture/valid.webp"}, true, "next"),
backupListPage([]string{"../escape"}, false, ""),
},
objects: map[string]fakeBackupObject{"picture/valid.webp": {body: []byte("valid")}},
}
require.Error(t, backupImagesWithClient(context.Background(), client, "bucket", t.TempDir(), ""))
require.Len(t, client.listInputs, 2)
require.Empty(t, client.getOrder)
})
for _, keys := range [][]string{{"a", "a/b"}, {"a/b", "a"}, {"same", "same"}} {
t.Run(fmt.Sprintf("collision %q", keys), func(t *testing.T) {
client := &fakeBackupS3{pages: []*s3.ListObjectsV2Output{backupListPage(keys, false, "")}}
require.Error(t, backupImagesWithClient(context.Background(), client, "bucket", t.TempDir(), ""))
require.Empty(t, client.getOrder)
})
}
t.Run("existing file blocks planned directory", func(t *testing.T) {
outDir := t.TempDir()
require.NoError(t, os.MkdirAll(filepath.Join(outDir, "images"), 0o700))
require.NoError(t, os.WriteFile(filepath.Join(outDir, "images", "a"), []byte("existing"), 0o600))
client := &fakeBackupS3{pages: []*s3.ListObjectsV2Output{backupListPage([]string{"a/b"}, false, "")}}
require.Error(t, backupImagesWithClient(context.Background(), client, "bucket", outDir, ""))
require.Empty(t, client.getOrder)
})
t.Run("existing directory blocks planned file", func(t *testing.T) {
outDir := t.TempDir()
require.NoError(t, os.MkdirAll(filepath.Join(outDir, "images", "a"), 0o700))
client := &fakeBackupS3{pages: []*s3.ListObjectsV2Output{backupListPage([]string{"a"}, false, "")}}
require.Error(t, backupImagesWithClient(context.Background(), client, "bucket", outDir, ""))
require.Empty(t, client.getOrder)
})
}
func TestBackupRetriesInterruptedStreamsAndLeavesNoPart(t *testing.T) {
t.Run("eventual success", func(t *testing.T) {
key := "picture/retry.webp"
body := []byte("complete-object-after-retries")
client := &fakeBackupS3{
pages: []*s3.ListObjectsV2Output{backupListPage([]string{key}, false, "")},
objects: map[string]fakeBackupObject{
key: {body: body, interruptedAttempts: 2, etag: "successful-get-etag"},
},
}
outDir := t.TempDir()
require.NoError(t, backupImagesWithClient(context.Background(), client, "bucket", outDir, ""))
require.Equal(t, 3, client.getCalls[key])
content, err := os.ReadFile(filepath.Join(outDir, "images", "picture", "retry.webp"))
require.NoError(t, err)
require.Equal(t, body, content)
requireNoPartFiles(t, filepath.Join(outDir, "images", "picture"))
})
t.Run("short body relative to GET content length", func(t *testing.T) {
key := "short-body.webp"
client := &fakeBackupS3{
pages: []*s3.ListObjectsV2Output{backupListPage([]string{key}, false, "")},
objects: map[string]fakeBackupObject{
key: {body: []byte("complete-on-second-attempt"), wrongLengthAttempts: 1},
},
}
outDir := t.TempDir()
require.NoError(t, backupImagesWithClient(context.Background(), client, "bucket", outDir, ""))
require.Equal(t, 2, client.getCalls[key])
requireNoPartFiles(t, filepath.Join(outDir, "images"))
})
t.Run("final failure", func(t *testing.T) {
key := "retry.txt"
client := &fakeBackupS3{
pages: []*s3.ListObjectsV2Output{backupListPage([]string{key}, false, "")},
objects: map[string]fakeBackupObject{
key: {body: []byte("never-complete"), interruptedAttempts: 3},
},
}
outDir := t.TempDir()
err := backupImagesWithClient(context.Background(), client, "bucket", outDir, "")
require.Error(t, err)
require.Contains(t, err.Error(), "after 3 attempts")
require.Equal(t, 3, client.getCalls[key])
require.NoFileExists(t, filepath.Join(outDir, "images", key))
requireNoPartFiles(t, filepath.Join(outDir, "images"))
require.NoFileExists(t, filepath.Join(outDir, "images-manifest.json"))
})
}
type capturedRestorePut struct {
key string
body []byte
contentType string
cacheControl string
size int64
}
type fakeRestoreStore struct {
existing map[string]bool
headErrors map[string]error
putFailures map[string]error
headCalls []string
puts []capturedRestorePut
}
func (f *fakeRestoreStore) HeadObject(_ context.Context, input *s3.HeadObjectInput, _ ...func(*s3.Options)) (*s3.HeadObjectOutput, error) {
key := aws.ToString(input.Key)
f.headCalls = append(f.headCalls, key)
if err := f.headErrors[key]; err != nil {
return nil, err
}
if f.existing[key] {
return &s3.HeadObjectOutput{}, nil
}
return nil, &types.NotFound{}
}
func (f *fakeRestoreStore) PutObject(_ context.Context, input *s3.PutObjectInput) error {
body, err := io.ReadAll(input.Body)
if err != nil {
return err
}
key := aws.ToString(input.Key)
f.puts = append(f.puts, capturedRestorePut{
key: key,
body: body,
contentType: aws.ToString(input.ContentType),
cacheControl: aws.ToString(input.CacheControl),
size: aws.ToInt64(input.ContentLength),
})
return f.putFailures[key]
}
type restoreFixtureObject struct {
key string
body []byte
storedBody []byte
manifestSize *int64
manifestSHA string
contentType string
cacheControl string
}
func createRestoreFixture(t *testing.T, objects []restoreFixtureObject) string {
t.Helper()
dir := t.TempDir()
manifest := make([]imageManifestEntry, 0, len(objects))
for _, object := range objects {
storedBody := object.storedBody
if storedBody == nil {
storedBody = object.body
}
path := filepath.Join(dir, "images", filepath.FromSlash(object.key))
require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o700))
require.NoError(t, os.WriteFile(path, storedBody, 0o600))
size := int64(len(object.body))
if object.manifestSize != nil {
size = *object.manifestSize
}
digest := sha256.Sum256(object.body)
hash := fmt.Sprintf("%x", digest)
if object.manifestSHA != "" {
hash = object.manifestSHA
}
manifest = append(manifest, imageManifestEntry{
Key: object.key,
Size: size,
SHA256: hash,
ETag: "source-get-etag",
ContentType: object.contentType,
CacheControl: object.cacheControl,
})
}
data, err := json.MarshalIndent(manifest, "", " ")
require.NoError(t, err)
require.NoError(t, os.WriteFile(filepath.Join(dir, "images-manifest.json"), data, 0o600))
return dir
}
func TestRestoreImagesPreservesKeysContentAndMetadataWithTargetPrefix(t *testing.T) {
objects := []restoreFixtureObject{
{key: "2026/11/04/root.webp", body: []byte("root-body"), contentType: "image/webp", cacheControl: "public, max-age=60"},
{key: "picture/2026/11/04/pic.webp", body: []byte("picture-body"), contentType: "image/webp", cacheControl: "public, max-age=120"},
{key: "static/site.css", body: []byte("body{}"), contentType: "text/css", cacheControl: "no-cache"},
}
input := createRestoreFixture(t, objects)
store := &fakeRestoreStore{}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{
Input: input,
Yes: true,
TargetPrefix: "isolated-restore", // 不带斜杠也应规范化为恰好一个路径分隔符。
})
require.NoError(t, err)
require.Len(t, store.headCalls, len(objects))
require.Len(t, store.puts, len(objects))
byKey := make(map[string]capturedRestorePut, len(store.puts))
for _, put := range store.puts {
byKey[put.key] = put
}
for _, object := range objects {
target := "isolated-restore/" + object.key
put := byKey[target]
require.Equal(t, object.body, put.body)
require.Equal(t, object.contentType, put.contentType)
require.Equal(t, object.cacheControl, put.cacheControl)
require.Equal(t, int64(len(object.body)), put.size)
}
}
func TestRestoreImagesDefaultRefusesOverwriteWithZeroPut(t *testing.T) {
objects := []restoreFixtureObject{
{key: "first.webp", body: []byte("first")},
{key: "second.webp", body: []byte("second")},
}
store := &fakeRestoreStore{existing: map[string]bool{"second.webp": true}}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{
Input: createRestoreFixture(t, objects),
Yes: true,
})
require.Error(t, err)
require.Contains(t, err.Error(), "no objects were uploaded")
require.Empty(t, store.puts)
}
func TestRestoreImagesOverwriteAndDryRun(t *testing.T) {
t.Run("overwrite", func(t *testing.T) {
store := &fakeRestoreStore{existing: map[string]bool{"picture.webp": true}}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{
Input: createRestoreFixture(t, []restoreFixtureObject{{key: "picture.webp", body: []byte("replacement")}}),
Yes: true,
Overwrite: true,
})
require.NoError(t, err)
require.Empty(t, store.headCalls, "显式 overwrite 不需要默认防覆盖 Head")
require.Len(t, store.puts, 1)
require.Equal(t, []byte("replacement"), store.puts[0].body)
})
t.Run("dry run without yes", func(t *testing.T) {
store := &fakeRestoreStore{}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{
Input: createRestoreFixture(t, []restoreFixtureObject{{key: "picture.webp", body: []byte("dry-run")}}),
DryRun: true,
TargetPrefix: "drill/",
})
require.NoError(t, err)
require.Equal(t, []string{"drill/picture.webp"}, store.headCalls)
require.Empty(t, store.puts)
})
t.Run("actual write requires yes", func(t *testing.T) {
store := &fakeRestoreStore{}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{
Input: createRestoreFixture(t, []restoreFixtureObject{{key: "picture.webp", body: []byte("write")}}),
})
require.Error(t, err)
require.Contains(t, err.Error(), "--yes")
require.Empty(t, store.headCalls)
require.Empty(t, store.puts)
})
}
func TestRestoreRejectsTamperedFilesBeforeAnyRemoteCall(t *testing.T) {
wrongSize := int64(999)
tests := []struct {
name string
second restoreFixtureObject
}{
{
name: "SHA256 tamper with unchanged size",
second: restoreFixtureObject{
key: "second.webp", body: []byte("second"), storedBody: []byte("SECOND"),
},
},
{
name: "size tamper",
second: restoreFixtureObject{
key: "second.webp", body: []byte("second"), manifestSize: &wrongSize,
},
},
{
name: "manifest hash tamper",
second: restoreFixtureObject{
key: "second.webp", body: []byte("second"), manifestSHA: strings.Repeat("0", 64),
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
store := &fakeRestoreStore{}
input := createRestoreFixture(t, []restoreFixtureObject{
{key: "first.webp", body: []byte("first")},
tt.second,
})
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{Input: input, Yes: true})
require.Error(t, err)
require.Empty(t, store.headCalls, "全部本地文件应在任何远端操作前完成校验")
require.Empty(t, store.puts, "首个有效文件也不能在后续文件校验失败前上传")
})
}
}
func TestReadImageManifestRejectsInvalidStructure(t *testing.T) {
validHash := strings.Repeat("a", 64)
tests := []struct {
name string
json string
}{
{name: "null", json: `null`},
{name: "trailing JSON", json: `[] {}`},
{name: "trailing garbage", json: `[] garbage`},
{name: "duplicate key", json: fmt.Sprintf(`[{"key":"same","size":0,"sha256":%q},{"key":"same","size":0,"sha256":%q}]`, validHash, validHash)},
{name: "short hash", json: `[{"key":"image","size":1,"sha256":"abc"}]`},
{name: "non hex hash", json: fmt.Sprintf(`[{"key":"image","size":1,"sha256":%q}]`, strings.Repeat("z", 64))},
{name: "negative size", json: fmt.Sprintf(`[{"key":"image","size":-1,"sha256":%q}]`, validHash)},
{name: "path traversal", json: fmt.Sprintf(`[{"key":"../image","size":1,"sha256":%q}]`, validHash)},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
path := filepath.Join(t.TempDir(), "images-manifest.json")
// 非数组用例直接保留原 JSON；其余用例同样应被解析层拒绝。
require.NoError(t, os.WriteFile(path, []byte(tt.json), 0o600))
_, err := readImageManifest(path)
require.Error(t, err)
})
}
}
func TestRestoreRejectsSymlinkBeforeRemoteCalls(t *testing.T) {
input := createRestoreFixture(t, []restoreFixtureObject{{key: "picture.webp", body: []byte("content")}})
source := filepath.Join(input, "images", "picture.webp")
outside := filepath.Join(t.TempDir(), "outside.webp")
require.NoError(t, os.WriteFile(outside, []byte("content"), 0o600))
require.NoError(t, os.Remove(source))
if err := os.Symlink(outside, source); err != nil {
t.Skipf("当前平台无法创建 symlink：%v", err)
}
store := &fakeRestoreStore{}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{Input: input, DryRun: true})
require.Error(t, err)
require.Empty(t, store.headCalls)
require.Empty(t, store.puts)
}
func TestRestoreReportsPartialFailureWithoutClaimingTransaction(t *testing.T) {
store := &fakeRestoreStore{putFailures: map[string]error{"second.webp": errors.New("injected put failure")}}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{
Input: createRestoreFixture(t, []restoreFixtureObject{
{key: "first.webp", body: []byte("first")},
{key: "second.webp", body: []byte("second")},
}),
Yes: true,
})
require.Error(t, err)
require.Contains(t, err.Error(), "1 successful uploads")
require.Contains(t, err.Error(), "not transactional")
require.Len(t, store.puts, 2)
}
func TestRestoreRejectsUnsafeTargetPrefixBeforeRemoteCalls(t *testing.T) {
store := &fakeRestoreStore{}
err := restoreImagesWithStore(context.Background(), store, "bucket", restoreImagesOptions{
Input: createRestoreFixture(t, []restoreFixtureObject{{key: "picture.webp", body: []byte("content")}}),
Yes: true,
TargetPrefix: "../outside/",
})
require.Error(t, err)
require.Empty(t, store.headCalls)
require.Empty(t, store.puts)
}
internal/cmd/backup_test.go
-96
View File
@@ -1,96 +0,0 @@
package cmd
import (
"encoding/json"
"errors"
"flag"
"io"
"os"
"path/filepath"
"testing"
"github.com/stretchr/testify/require"
"github.com/urfave/cli/v2"
)
func TestRunBackupRejectsMutuallyExclusiveModes(t *testing.T) {
set := flag.NewFlagSet("backup", flag.ContinueOnError)
set.Bool("db-only", true, "")
set.Bool("images-only", true, "")
err := runBackup(cli.NewContext(nil, set, nil))
require.EqualError(t, err, "--db-only and --images-only cannot be used together")
}
func TestWriteFileAtomically(t *testing.T) {
t.Run("success", func(t *testing.T) {
dir := t.TempDir()
target := filepath.Join(dir, "backup.sql")
require.NoError(t, writeFileAtomically(target, func(w io.Writer) error {
_, err := io.WriteString(w, "complete backup")
return err
}))
content, err := os.ReadFile(target)
require.NoError(t, err)
require.Equal(t, "complete backup", string(content))
requireNoPartFiles(t, dir)
})
t.Run("failure preserves previous backup", func(t *testing.T) {
dir := t.TempDir()
target := filepath.Join(dir, "backup.sql")
require.NoError(t, os.WriteFile(target, []byte("known good"), 0o600))
writeErr := errors.New("dump failed")
err := writeFileAtomically(target, func(w io.Writer) error {
_, _ = io.WriteString(w, "partial")
return writeErr
})
require.ErrorIs(t, err, writeErr)
content, err := os.ReadFile(target)
require.NoError(t, err)
require.Equal(t, "known good", string(content))
requireNoPartFiles(t, dir)
})
t.Run("failure leaves no new backup", func(t *testing.T) {
dir := t.TempDir()
target := filepath.Join(dir, "backup.sql")
writeErr := errors.New("dump failed")
err := writeFileAtomically(target, func(w io.Writer) error {
_, _ = io.WriteString(w, "partial")
return writeErr
})
require.ErrorIs(t, err, writeErr)
require.NoFileExists(t, target)
requireNoPartFiles(t, dir)
})
}
func requireNoPartFiles(t *testing.T, dir string) {
t.Helper()
matches, err := filepath.Glob(filepath.Join(dir, "*.part"))
require.NoError(t, err)
require.Empty(t, matches)
}
func TestImageManifestEntryIntegrityFields(t *testing.T) {
entry := imageManifestEntry{
Key: "tamabox/image.webp",
Size: 3,
SHA256: "actual-content-sha256",
ETag: "provider-etag",
}
encoded, err := json.Marshal(entry)
require.NoError(t, err)
require.JSONEq(t, `{
"key":"tamabox/image.webp",
"size":3,
"sha256":"actual-content-sha256",
"etag":"provider-etag"
}`, string(encoded))
require.NotContains(t, string(encoded), "md5")
}
internal/cmd/ban.go
+1 -3
View File
@@ -95,9 +95,7 @@ func runBan(ctx *cli.Context) error {
return errors.Wrap(err, "ban user and cleanup")
}
// 数据库事务已经提交，先明确输出这一事实，再进行非事务性的 R2 清理。
logrus.WithField("user_id", user.ID).Info("数据库封禁与关联数据清理已提交")
drainR2OutboxAfterBan(ctx.Context)
logrus.WithField("user_id", user.ID).Info("用户已封禁，关联数据已清理")
return nil
}
internal/cmd/hide_public.go
-158
View File
@@ -1,158 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"fmt"
"strings"
"time"
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
"github.com/urfave/cli/v2"
"gorm.io/gorm"
"github.com/tamakyi/TamaBox/internal/db"
)
// HidePublic 把某箱主已公开的回答批量转为私密。
//
// 存在意义：处置一个「组织挂人」的箱主时，L1 只停分发、L2 只影响新内容，
// 已经挂在上面的几十上百条旧内容仍然公开可访问。逐条点后台不现实，
// 而直接封号又过重（这类账号往往同时有大量正常内容）。
//
// 默认**只动「公开且已回答」的题**：未回答的本来就不公开，已私密的不必再动，
// 不会误伤草稿态数据。加上 --only-reported 可进一步只处理「有未处理举报」的条，
// 这是最精准的用法 —— 只收掉被投诉的部分，其余正常内容保留。
var HidePublic = &cli.Command{
Name: "hide-public",
Usage: "Hide all public answers of a user (set is_private = true)",
Flags: []cli.Flag{
&cli.StringFlag{Name: "email", Usage: "Email of the user"},
&cli.StringFlag{Name: "domain", Usage: "Custom domain of the user"},
&cli.BoolFlag{Name: "only-reported", Usage: "Only hide questions that have pending reports"},
&cli.IntFlag{Name: "since", Usage: "Only hide questions created within the last N days (0 = all)"},
&cli.BoolFlag{Name: "yes", Usage: "Skip confirmation"},
},
Action: runHidePublic,
}
func runHidePublic(ctx *cli.Context) error {
database, err := openDatabase()
if err != nil {
return err
}
user, err := findTargetUser(database, ctx.String("email"), ctx.String("domain"))
if err != nil {
return err
}
onlyReported := ctx.Bool("only-reported")
sinceDays := ctx.Int("since")
if sinceDays < 0 {
return errors.New("--since must not be negative")
}
// ⚠️ 每次都重新构建 query：GORM 的链式对象在 Count/Find 之后会带上 Statement 状态，
// 复用同一个实例做「统计 → 预览 → 更新」会导致条件互相污染。
build := func() *gorm.DB {
q := database.Model(&db.Question{}).
Where("user_id = ? AND answer != '' AND is_private = false", user.ID)
if onlyReported {
q = q.Where("id IN (?)", database.Model(&db.ContentReport{}).
Select("question_id").
Where("status = ?", db.ReportStatusPending))
}
if sinceDays > 0 {
q = q.Where("created_at >= ?", time.Now().AddDate(0, 0, -sinceDays))
}
return q
}
var total int64
if err := build().Count(&total).Error; err != nil {
return errors.Wrap(err, "count public questions")
}
fmt.Printf("箱主: %s (@%s) id=%d\n", user.Name, user.Domain, user.ID)
if onlyReported {
fmt.Println("范围: 仅「有未处理举报」的公开回答")
} else {
fmt.Println("范围: 全部公开回答")
}
if sinceDays > 0 {
fmt.Printf("时间: 仅最近 %d 天\n", sinceDays)
}
if total == 0 {
fmt.Println("没有需要隐藏的内容")
return nil
}
var preview []*db.Question
if err := build().Order("id DESC").Limit(10).Find(&preview).Error; err != nil {
return errors.Wrap(err, "preview questions")
}
fmt.Printf("将把 %d 条回答转为私密（最新 10 条预览）：\n", total)
for _, q := range preview {
fmt.Printf(" #%-6d %s %s\n", q.ID, q.CreatedAt.Format("2006-01-02 15:04"), truncateForCLI(q.Content, 44))
}
if total > int64(len(preview)) {
fmt.Printf(" ...（其余 %d 条略）\n", total-int64(len(preview)))
}
if !ctx.Bool("yes") {
logrus.Warn("输入大写 YES 确认执行（可逆：箱主可在后台逐条重新设为公开）：")
var answer string
if _, err := fmtScan(&answer); err != nil {
return errors.Wrap(err, "read confirmation")
}
if answer != "YES" {
return errors.New("已取消")
}
}
// ⚠️ 必须先快照目标 ID 再更新：build() 的条件里有 is_private = false，
// 一旦执行了 Update，再拿 build() 当子查询就恒为空集，举报闭环会静默失效
// （实测：隐藏成功但 content_reports 仍是 pending）。
var targetIDs []uint
if err := build().Pluck("id", &targetIDs).Error; err != nil {
return errors.Wrap(err, "collect target question ids")
}
if len(targetIDs) == 0 {
fmt.Println("没有需要隐藏的内容")
return nil
}
result := database.Model(&db.Question{}).Where("id IN ?", targetIDs).Update("is_private", true)
if result.Error != nil {
return errors.Wrap(result.Error, "hide public questions")
}
logrus.WithFields(logrus.Fields{
"user_id": user.ID,
"affected": result.RowsAffected,
"only_reported": onlyReported,
}).Warn("公开回答已批量转为私密")
// 举报闭环：被隐藏的内容等同于已处理，对应的待处理举报一并标记为成立，
// 否则这些举报会继续计入告警阈值（详见 internal/db/report.go 的说明）。
accepted := database.WithContext(ctx.Context).
Model(&db.ContentReport{}).
Where("question_id IN ?", targetIDs).
Where("status = ?", db.ReportStatusPending).
Update("status", db.ReportStatusAccepted)
if accepted.Error != nil {
logrus.WithError(accepted.Error).Warn("标记举报为已处理时异常（内容隐藏已生效，可稍后手动处理）")
} else if accepted.RowsAffected > 0 {
fmt.Printf("同时把 %d 条待处理举报标记为已处理\n", accepted.RowsAffected)
}
fmt.Printf("完成：%d 条已转为私密\n", result.RowsAffected)
fmt.Println(strings.TrimSpace(`
注意：这只改变可见性，不改变回答内容；箱主仍可在自己的后台逐条改回公开。
如果目的是「停止分发」，还需要配合：TamaBox restrict --domain <domain> --level L1 --days N`))
return nil
}
internal/cmd/honeypot.go
-568
View File
@@ -1,568 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"context"
"fmt"
"sort"
"strings"
"time"
"github.com/pkg/errors"
"github.com/urfave/cli/v2"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/db"
"github.com/tamakyi/TamaBox/internal/security/honeypot"
"github.com/tamakyi/TamaBox/internal/shared"
)
// Honeypot 提供蜜罐取证命令（只读 + 一条显式清理）。
//
// TamaBox honeypot hits --since 24h 列出捕获到的破解凭据
// TamaBox honeypot stats --days 7 统计来源/路径/凭据排行
// TamaBox honeypot size 报告表行数与磁盘占用
// TamaBox honeypot report --period week 生成安全汇总周报（含地图）并发邮件
// TamaBox honeypot prune --days 30 清理过期记录（保留期由配置决定）
//
// 密码默认脱敏：CLI 输出会被贴到工单、聊天窗口甚至截图里，
// 明文只在确有取证需要时用 --show-password 显式打开。
var Honeypot = &cli.Command{
Name: "honeypot",
Usage: "Inspect honeypot hits (fake admin login page credential capture)",
Subcommands: []*cli.Command{
{
Name: "hits",
Usage: "List captured credential submissions",
Flags: []cli.Flag{
&cli.StringFlag{Name: "since", Value: "24h", Usage: "Time window, e.g. 24h / 7d / 30m"},
&cli.IntFlag{Name: "limit", Value: 50, Usage: "Max rows to print"},
&cli.StringFlag{Name: "ip", Usage: "Only show hits from this source IP"},
&cli.BoolFlag{Name: "show-password", Usage: "Print passwords in plaintext (default: masked)"},
},
Action: runHoneypotHits,
},
{
Name: "stats",
Usage: "Show honeypot statistics (top sources / paths / credentials)",
Flags: []cli.Flag{
&cli.IntFlag{Name: "days", Value: 7, Usage: "Statistics window in days"},
&cli.IntFlag{Name: "limit", Value: 20, Usage: "Max rows per section"},
&cli.BoolFlag{Name: "show-password", Usage: "Print passwords in plaintext (default: masked)"},
},
Action: runHoneypotStats,
},
{
Name: "prune",
Usage: "Delete honeypot records (DB metadata + credential files) older than the retention period",
Flags: []cli.Flag{
&cli.IntFlag{Name: "days", Value: 0, Usage: "Days to keep (0 = use honeypot_retain_days from config)"},
&cli.BoolFlag{Name: "yes", Usage: "Skip confirmation"},
},
Action: runHoneypotPrune,
},
{
Name: "size",
Usage: "Report honeypot table row count and disk usage",
Action: runHoneypotSize,
},
// 周期安全汇总：把命中按 IP 定位到城市，出地图报告并邮件送达。
reportCommand,
{
Name: "paths",
Usage: "List active decoy paths (built-in + honeypot_paths)",
Action: runHoneypotPaths,
},
{
Name: "purge-creds",
Usage: "Drop legacy credential columns (username/password/fields/raw_body) from honeypot_hits — irreversible",
Flags: []cli.Flag{
&cli.BoolFlag{Name: "yes", Usage: "Skip confirmation"},
},
Action: runHoneypotPurgeCreds,
},
},
}
// parseSince 解析 --since 参数，支持 30m / 24h / 7d / 2w。
func parseSince(s string) (time.Duration, error) {
s = strings.TrimSpace(strings.ToLower(s))
if s == "" {
return 24 * time.Hour, nil
}
unit := s[len(s)-1]
numPart := s[:len(s)-1]
var mult time.Duration
switch unit {
case 'm':
mult = time.Minute
case 'h':
mult = time.Hour
case 'd':
mult = 24 * time.Hour
case 'w':
mult = 7 * 24 * time.Hour
default:
return 0, errors.Errorf("invalid --since value %q (expect e.g. 30m / 24h / 7d)", s)
}
var n int
if _, err := fmt.Sscanf(numPart, "%d", &n); err != nil || n <= 0 {
return 0, errors.Errorf("invalid --since value %q", s)
}
return time.Duration(n) * mult, nil
}
// credStoreFromConfig 用已加载的配置打开凭据取证目录。
//
// 凭据（用户名/密码）只在文件里，不查数据库 —— 所以任何需要展示凭据的
// 命令都走这里，而不是 db.HoneypotStore。
func credStoreFromConfig() (honeypot.CredStore, error) {
return honeypot.NewFileCredStore(conf.Security.HoneypotCredDir)
}
func runHoneypotHits(ctx *cli.Context) error {
dur, err := parseSince(ctx.String("since"))
if err != nil {
return err
}
// 凭据只在取证文件里，本命令不再连数据库 —— DB 挂了也能查。
// （元数据在库里不含凭据内容，见 db.HoneypotHit.HadFields 的注释。）
if err := conf.Init(); err != nil {
return errors.Wrap(err, "load configuration")
}
store, err := credStoreFromConfig()
if err != nil {
return errors.Wrap(err, "open honeypot credential store")
}
since := time.Now().Add(-dur)
filterIP := strings.TrimSpace(ctx.String("ip"))
showPwd := ctx.Bool("show-password")
// IP 过滤在读取阶段做（列表本来就是流式读，先取最近 N 条再筛会让
// 指定 IP 的历史记录被其他 IP 挤出去）。
rows, err := store.ListSince(since, filterIP, ctx.Int("limit"))
if err != nil {
return errors.Wrap(err, "read honeypot credentials")
}
fmt.Printf("蜜罐凭据记录（近 %s，共 %d 条，来源 %s）\n", dur, len(rows), store.Dir())
fmt.Println(strings.Repeat("-", 72))
if len(rows) == 0 {
fmt.Println(" 无")
return nil
}
for _, r := range rows {
pwd := r.Password
if pwd == "" {
pwd = "(空)"
} else if !showPwd {
pwd = maskSecret(pwd)
}
user := r.Username
if user == "" {
user = "(空)"
}
fmt.Printf("%s %-8s %-6s %s\n", r.Time.Format("2006-01-02 15:04:05"), r.IP, r.Method, truncateForCLI(r.Path, 48))
fmt.Printf(" 用户名：%s 密码：%s\n", truncateForCLI(user, 64), truncateForCLI(pwd, 64))
if r.UserAgent != "" {
fmt.Printf(" UA：%s\n", truncateForCLI(r.UserAgent, 96))
}
if r.Banned {
fmt.Printf(" 处置：已触发封禁\n")
}
fmt.Println()
}
if !showPwd {
fmt.Println("提示：密码默认脱敏。需要明文时加 --show-password。")
}
return nil
}
func runHoneypotStats(ctx *cli.Context) error {
days := ctx.Int("days")
if days <= 0 {
days = 7
}
database, err := openDatabase()
if err != nil {
return err
}
store := db.NewHoneypotStore(database)
cctx := context.Background()
since := time.Now().AddDate(0, 0, -days)
total, err := store.CountSince(cctx, since)
if err != nil {
return errors.Wrap(err, "count honeypot hits")
}
// 元数据表存的是精确地址（取证需要），但 IPv6 攻击者常在一个 /64 内轮换地址：
// 直接按精确 IP 排行会碎成几十条各 1 次的记录，看不出「其实是同一个人」。
// 多取一些再按封禁同口径（/64）合并，见 mergeSourcesByKey。
limit := ctx.Int("limit")
if limit <= 0 {
limit = 20
}
sources, err := store.TopSources(cctx, since, limit*4)
if err != nil {
return errors.Wrap(err, "query top sources")
}
sources = mergeSourcesByKey(sources, limit)
paths, err := store.TopPaths(cctx, since, ctx.Int("limit"))
if err != nil {
return errors.Wrap(err, "query top paths")
}
credStore, err := credStoreFromConfig()
if err != nil {
return errors.Wrap(err, "open honeypot credential store")
}
creds, err := credStore.TopCredentials(since, ctx.Int("limit"))
if err != nil {
return errors.Wrap(err, "query top credentials")
}
fmt.Printf("蜜罐统计：近 %d 天，共 %d 次命中\n", days, total)
fmt.Println(strings.Repeat("-", 72))
fmt.Println("来源排行（IPv6 按 /64 聚合，与封禁口径一致）：")
if len(sources) == 0 {
fmt.Println(" 无")
}
for i, s := range sources {
fmt.Printf(" %2d. %-40s %5d 次 %s\n", i+1, s.IP, s.Count, s.Provider)
}
fmt.Println()
fmt.Println("被探测路径排行：")
if len(paths) == 0 {
fmt.Println(" 无")
}
for i, p := range paths {
fmt.Printf(" %2d. %-50s %5d 次\n", i+1, truncateForCLI(p.Path, 50), p.Count)
}
fmt.Println()
fmt.Println("最常被尝试的凭据组合（来自取证文件，非数据库）：")
if len(creds) == 0 {
fmt.Println(" 无")
}
showPwd := ctx.Bool("show-password")
for i, c := range creds {
pwd := c.Password
if pwd == "" {
pwd = "(空)"
} else if !showPwd {
pwd = maskSecret(pwd)
}
user := c.Username
if user == "" {
user = "(空)"
}
fmt.Printf(" %2d. %-30s %-30s %5d 次\n", i+1, truncateForCLI(user, 30), truncateForCLI(pwd, 30), c.Count)
}
if !showPwd {
fmt.Println()
fmt.Println("提示：密码默认脱敏。需要明文时加 --show-password。")
}
return nil
}
func runHoneypotPrune(ctx *cli.Context) error {
days := ctx.Int("days")
if days <= 0 {
days = conf.Security.HoneypotRetainDays
}
if days <= 0 {
days = 30
}
database, err := openDatabase()
if err != nil {
return err
}
before := time.Now().AddDate(0, 0, -days)
if !ctx.Bool("yes") {
fmt.Printf("将删除 %s 之前的蜜罐记录（共保留 %d 天）。\n", before.Format("2006-01-02 15:04:05"), days)
fmt.Print("确认继续？输入 yes 继续：")
var answer string
if _, err := fmt.Scanln(&answer); err != nil || strings.TrimSpace(answer) != "yes" {
fmt.Println("已取消。")
return nil
}
}
store := db.NewHoneypotStore(database)
n, err := store.DeleteBefore(context.Background(), before)
if err != nil {
return errors.Wrap(err, "prune honeypot records")
}
fmt.Printf("已删除 %d 条过期蜜罐记录。\n", n)
// 回收物理空间：PostgreSQL 的 DELETE 只标记死元组，表文件不会变小。
// 不回收的话「清理」只是逻辑变小，磁盘占用继续单调增长。
if n > 0 {
if err := store.Compact(context.Background()); err != nil {
fmt.Printf("提示：空间回收失败（%v），数据本身已正确删除；PostgreSQL 下可手动执行 VACUUM honeypot_hits。\n", err)
}
}
// 凭据文件同样会过期，一并清理：明文账号密码不该比元数据留得更久。
// 这也让「prune」在运维心里只有一个语义 —— 按保留期清干净，不用记两套。
if cs, err := credStoreFromConfig(); err != nil {
fmt.Printf("提示：无法打开凭据目录，凭据文件未清理（%v）。\n", err)
} else if m, err := cs.PurgeBefore(before); err != nil {
fmt.Printf("提示：凭据文件清理失败（%v）。\n", err)
} else if m > 0 {
fmt.Printf("已删除 %d 个过期凭据文件（%s）。\n", m, cs.Dir())
}
return nil
}
// runHoneypotSize 报告蜜罐表的行数与磁盘占用。
//
// 这个命令存在的意义：把「会不会把数据库撑臃肿」变成运维随时能自己查的事，
// 而不是只能等开发一次性汇报。
func runHoneypotSize(ctx *cli.Context) error {
database, err := openDatabase()
if err != nil {
return err
}
store := db.NewHoneypotStore(database)
info, err := store.Size(context.Background())
if err != nil {
return errors.Wrap(err, "query honeypot table size")
}
fmt.Println("蜜罐表体积")
fmt.Println(strings.Repeat("-", 72))
fmt.Printf(" 表名：honeypot_hits\n")
fmt.Printf(" 存活记录：%d 条\n", info.Rows)
if info.Bytes > 0 {
fmt.Printf(" 磁盘占用：%s（含索引）\n", humanBytes(info.Bytes))
if info.Rows > 0 {
fmt.Printf(" 单条均摊：%d 字节\n", info.Bytes/info.Rows)
}
} else {
fmt.Printf(" 磁盘占用：（当前数据库不支持元数据查询）\n")
}
if info.Oldest != nil && info.Newest != nil {
fmt.Printf(" 时间跨度：%s → %s\n",
info.Oldest.Format("2006-01-02 15:04"),
info.Newest.Format("2006-01-02 15:04"))
}
fmt.Println()
// 与配置中的两道闸对照，让运维一眼看出「当前是否在界内」。
maxRows := conf.Security.HoneypotMaxRows
retainDays := conf.Security.HoneypotRetainDays
if maxRows > 0 {
fmt.Printf("行数上限：%d 条（当前 %d 条，%s）\n", maxRows, info.Rows, usageRatio(info.Rows, int64(maxRows)))
} else {
fmt.Printf("行数上限：未设置（当前 %d 条）\n", info.Rows)
}
if retainDays > 0 {
fmt.Printf("保留期：%d 天（自动清理 %s）\n", retainDays, onOff(conf.Security.HoneypotAutoClean))
} else {
fmt.Printf("保留期：未设置 —— 记录只增不减，需要手动执行 TamaBox honeypot prune\n")
}
// 凭据与元数据是两套存储，体积必须分开看：
// 数据库里只有元数据，明文账号密码在文件里。
fmt.Println()
if cs, err := credStoreFromConfig(); err == nil {
if n, size, err := cs.Size(); err == nil {
fmt.Printf("凭据取证文件：%d 个，%s\n", n, humanBytes(size))
fmt.Printf(" 目录：%s\n", cs.Dir())
fmt.Println(" 说明：用户名/密码只存在这里，不入库；按天一个文件，随保留期一并清理。")
}
}
return nil
}
// runHoneypotPaths 列出当前生效的诱饵路径。
//
// 存在的意义：honeypot_paths 是自由文本配置，写错了（拼错、写成正则、漏斜杠）
// 从任何输出里都看不出来 —— 这个命令让「我配的到底生效没」变成一条可查的事实。
func runHoneypotPaths(ctx *cli.Context) error {
// 本命令不查库（DB 挂掉时也能查配置），因此不能走 openDatabase 那条
// 顺带 conf.Init 的路径 —— 必须显式加载，否则读到的全是零值，
// 会显示「蜜罐关闭」并把 honeypot_paths 吞掉。
if err := conf.Init(); err != nil {
return errors.Wrap(err, "load configuration")
}
extra := honeypot.SplitPaths(conf.Security.HoneypotPaths)
builtin := honeypot.New(honeypot.Options{Enabled: true}).Prefixes()
active := honeypot.New(honeypot.Options{Enabled: true, ExtraPaths: extra}).Prefixes()
fmt.Printf("蜜罐开关：%s\n", onOff(conf.Security.EnableHoneypot))
if !conf.Security.EnableHoneypot {
fmt.Println("提示：enable_honeypot = false，以下路径当前不会接管任何请求。")
}
fmt.Println(strings.Repeat("-", 72))
fmt.Printf("生效诱饵路径：%d 条（内置 %d + 自定义 %d，重名已合并）\n",
len(active), len(builtin), len(extra))
// 按家族汇总：运维真正关心的是「哪几类后台在伪装」，而不是 100 条路径。
// 家族决定返回哪种登录页（WordPress / phpMyAdmin / Jenkins / Tomcat …）。
counts := make(map[honeypot.Family]int, len(honeypot.Families()))
for _, p := range active {
counts[honeypot.FamilyOf(p)]++
}
parts := make([]string, 0, len(counts))
for _, fam := range honeypot.Families() {
if n := counts[fam]; n > 0 {
parts = append(parts, fmt.Sprintf("%s %d", fam, n))
}
}
fmt.Println("伪装家族：" + strings.Join(parts, " / "))
for _, p := range active {
fmt.Println(" " + p)
}
if len(extra) > 0 {
fmt.Println()
fmt.Println("自定义路径（honeypot_paths）：")
for _, p := range extra {
fmt.Println(" " + p)
}
}
return nil
}
// runHoneypotPurgeCreds 删除旧版本留在 honeypot_hits 上的明文凭据列。
//
// 为什么需要：结构体早已去掉这些字段，但 GORM 的 AutoMigrate **不删既有列**，
// 老库升级上来后历史明文仍在，还会跟着进备份与主从复制。
// DROP COLUMN 不可逆，所以做成显式命令 + 二次确认，不放启动流程里自动执行
// （启动时只会 WARN 提示）。
func runHoneypotPurgeCreds(ctx *cli.Context) error {
database, err := openDatabase()
if err != nil {
return err
}
store := db.NewHoneypotStore(database)
cols, err := store.LegacyCredentialColumns(context.Background())
if err != nil {
return errors.Wrap(err, "check legacy credential columns")
}
if len(cols) == 0 {
fmt.Println("honeypot_hits 上没有遗留的凭据列，无需清理。")
return nil
}
fmt.Println("honeypot_hits 上仍存在以下旧版明文凭据列（整列删除，不可逆）：")
for _, c := range cols {
fmt.Println(" " + c)
}
fmt.Println("注意：本命令只处理数据库；磁盘上的历史备份需要你自行处理。")
if !ctx.Bool("yes") {
fmt.Print("确认继续？输入 yes 继续：")
var answer string
if _, err := fmt.Scanln(&answer); err != nil || strings.TrimSpace(answer) != "yes" {
fmt.Println("已取消。")
return nil
}
}
dropped, err := store.PurgeLegacyCredentialColumns(context.Background())
if err != nil {
return errors.Wrapf(err, "凭据列删除中途失败，已删除 %v", dropped)
}
fmt.Printf("已删除 %d 列：%s\n", len(dropped), strings.Join(dropped, ", "))
return nil
}
// usageRatio 给出当前用量相对上限的百分比描述。
func usageRatio(cur int64, max int64) string {
if max <= 0 {
return ""
}
pct := float64(cur) / float64(max) * 100
switch {
case pct >= 100:
return "已达上限"
case pct >= 80:
return "接近上限"
default:
return fmt.Sprintf("%.1f%%", pct)
}
}
func onOff(b bool) string {
if b {
return "已开启"
}
return "已关闭"
}
// humanBytes 把字节数格式化成人类可读形式。
func humanBytes(n int64) string {
const unit = 1024
if n < unit {
return fmt.Sprintf("%d B", n)
}
div, exp := int64(unit), 0
for v := n / unit; v >= unit; v /= unit {
div *= unit
exp++
}
return fmt.Sprintf("%.2f %cB", float64(n)/float64(div), "KMGTPE"[exp])
}
// maskSecret 对密码做保长脱敏：保留首尾各 1 位，中间固定长度星号。
// 目的是让运维能分辨「是不是同一个密码」，但不把字典直接摊在终端上。
func maskSecret(s string) string {
r := []rune(s)
switch {
case len(r) <= 2:
return strings.Repeat("*", len(r))
case len(r) <= 6:
return string(r[0]) + strings.Repeat("*", len(r)-2) + string(r[len(r)-1])
default:
return string(r[0]) + strings.Repeat("*", 6) + string(r[len(r)-1])
}
}
// mergeSourcesByKey 按「封禁 / 限流」的同一口径合并来源排行。
//
// 元数据表存的是精确地址（取证需要，见 db.HoneypotHit.IP），但 IPv6 攻击者
// 通常在一个 /64 内轮换地址：直接按精确 IP 排行会碎成几十条各 1 次的记录，
// 看不出「其实是同一台机器」。这里用 shared.LimitKey 折成 /64 ——
// 与 autoban 判定、限流的键完全一致，看到的排行就是「谁在被封」。
//
// 代价：SQL 只取了前 limit*4 条精确地址，极端长尾可能漏算，排行本身是近似展示。
func mergeSourcesByKey(rows []*db.HoneypotSourceStat, limit int) []*db.HoneypotSourceStat {
if len(rows) == 0 {
return rows
}
type agg struct {
count int64
provider string
}
merged := make(map[string]*agg, len(rows))
for _, r := range rows {
key := shared.LimitKey(r.IP)
if a, ok := merged[key]; ok {
a.count += r.Count
if a.provider == "" {
a.provider = r.Provider
}
continue
}
merged[key] = &agg{count: r.Count, provider: r.Provider}
}
out := make([]*db.HoneypotSourceStat, 0, len(merged))
for key, a := range merged {
out = append(out, &db.HoneypotSourceStat{IP: key, Count: a.count, Provider: a.provider})
}
sort.Slice(out, func(i, j int) bool {
if out[i].Count != out[j].Count {
return out[i].Count > out[j].Count
}
return out[i].IP < out[j].IP // 同次数时稳定排序，避免每次输出顺序抖动
})
if limit > 0 && len(out) > limit {
out = out[:limit]
}
return out
}
internal/cmd/honeypot_test.go
-46
View File
@@ -1,46 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"testing"
"github.com/tamakyi/TamaBox/internal/db"
)
// TestMergeSourcesByKey 验证来源排行按「封禁口径」合并（IPv6 折成 /64）。
//
// 元数据表存的是精确地址（取证需要），若排行榜也按精确地址分组，
// 一个在 /64 内轮换地址的扫描器会碎成几十条各 1 次的记录 ——
// 看起来像「很多人在扫」，其实只有一台机器。合并口径必须与 autoban 一致。
func TestMergeSourcesByKey(t *testing.T) {
rows := []*db.HoneypotSourceStat{
{IP: "2408:8207:1234:5678::1", Count: 5, Provider: "联通"},
{IP: "2408:8207:1234:5678::2", Count: 3},
{IP: "1.2.3.4", Count: 4, Provider: "Azure"},
{IP: "2408:8207:9999:0001::1", Count: 2},
}
got := mergeSourcesByKey(rows, 10)
if len(got) != 3 {
t.Fatalf("合并后条目数 = %d, want 3（同 /64 必须合并）", len(got))
}
if got[0].IP != "2408:8207:1234:5678::/64" || got[0].Count != 8 {
t.Errorf("第一名 = %s / %d, want 2408:8207:1234:5678::/64 / 8", got[0].IP, got[0].Count)
}
if got[0].Provider != "联通" {
t.Errorf("合并后应保留首个非空归属，got %q", got[0].Provider)
}
if got[1].IP != "1.2.3.4" || got[1].Count != 4 {
t.Errorf("第二名 = %s / %d, want 1.2.3.4 / 4（IPv4 原样保留）", got[1].IP, got[1].Count)
}
if limited := mergeSourcesByKey(rows, 1); len(limited) != 1 {
t.Errorf("limit=1 时条目数 = %d, want 1", len(limited))
}
if out := mergeSourcesByKey(nil, 10); len(out) != 0 {
t.Errorf("空输入应返回空，got %d", len(out))
}
}
internal/cmd/r2_outbox.go
-365
View File
@@ -1,365 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"context"
"errors"
"fmt"
"strings"
"sync"
"time"
"unicode/utf8"
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/sirupsen/logrus"
"github.com/urfave/cli/v2"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/db"
"github.com/tamakyi/TamaBox/internal/storage"
)
const (
r2OutboxDefaultLimit = 100
r2OutboxWorkerInterval = time.Minute
r2OutboxInitialBackoff = time.Minute
r2OutboxMaxBackoff = time.Hour
r2OutboxMaxLastErrorSize = 1024
)
var errR2OutboxNotConfigured = errors.New("R2 configuration is incomplete")
// R2Outbox 有界处理一批持久化的 R2 对象删除任务。
var R2Outbox = &cli.Command{
Name: "r2-outbox",
Usage: "Drain a bounded batch of pending R2 object deletion tasks",
Action: runR2Outbox,
Flags: []cli.Flag{
&cli.IntFlag{
Name: "limit",
Value: r2OutboxDefaultLimit,
Usage: "Maximum number of due tasks to process",
},
},
}
type r2OutboxTaskStore interface {
ListDue(ctx context.Context, limit int) ([]*db.R2DeleteTask, error)
Delete(id uint) error
MarkFailed(id uint, nextRetry time.Time, lastError string) error
HasReferences(ctx context.Context, bucket, key string) (bool, error)
}
type r2ObjectDeleter interface {
DeleteObject(ctx context.Context, bucket, key string) error
}
type r2S3ObjectDeleter struct {
client *s3.Client
}
func (d *r2S3ObjectDeleter) DeleteObject(ctx context.Context, bucket, key string) error {
return storage.DeleteObject(ctx, d.client, bucket, key)
}
type r2OutboxResult struct {
Listed int
Removed int
ObjectsDeleted int
ReferenceOnly int
Failed int
Skipped int
Remaining int
}
// processR2Outbox 串行处理一批到期任务。单个任务失败不会中断同批后续任务；
// context 取消则立即停止，且不会把关闭过程中的取消误记为一次任务失败。
func processR2Outbox(ctx context.Context, store r2OutboxTaskStore, deleter r2ObjectDeleter, limit int) (result r2OutboxResult, err error) {
defer func() {
result.Remaining = result.Listed - result.Removed
}()
tasks, err := store.ListDue(ctx, limit)
if err != nil {
if ctx.Err() != nil {
return result, ctx.Err()
}
return result, fmt.Errorf("list R2 outbox tasks: %s", sanitizeR2OutboxError(err))
}
result.Listed = len(tasks)
for _, task := range tasks {
if err := ctx.Err(); err != nil {
return result, err
}
if task == nil {
result.Failed++
logrus.Warn("R2 outbox 返回了空任务，已跳过")
continue
}
logger := logrus.WithField("task_id", task.ID)
if task.Bucket != conf.Upload.ImageBucket {
result.Skipped++
logger.Warn("R2 outbox 任务 bucket 与当前配置不匹配，任务已保留")
continue
}
referenced, refErr := store.HasReferences(ctx, task.Bucket, task.Key)
if ctx.Err() != nil {
return result, ctx.Err()
}
if refErr != nil {
result.Failed++
markR2OutboxTaskFailed(store, task, refErr)
continue
}
if referenced {
// 还有引用时只清理过期 outbox 记录，绝不删除对象。最后一个引用被
// 删除时，对应数据库事务会重新入队一条任务。
if err := store.Delete(task.ID); err != nil {
result.Failed++
logger.WithField("error", sanitizeR2OutboxError(err)).Warn("R2 outbox 引用任务清理失败，任务已保留")
continue
}
result.Removed++
result.ReferenceOnly++
continue
}
deleteErr := deleter.DeleteObject(ctx, task.Bucket, task.Key)
if deleteErr != nil && !isS3ObjectNotFound(deleteErr) {
if ctx.Err() != nil {
return result, ctx.Err()
}
result.Failed++
markR2OutboxTaskFailed(store, task, deleteErr)
continue
}
// storage.DeleteObject 已将 404 归一为成功；这里再次识别 404，保证其他
// deleter 实现也遵循相同的幂等语义。只有任务记录也删除后才算完成。
if err := store.Delete(task.ID); err != nil {
result.Failed++
logger.WithField("error", sanitizeR2OutboxError(err)).Warn("R2 对象已删除，但 outbox 任务清理失败；后续将幂等重试")
continue
}
result.Removed++
result.ObjectsDeleted++
}
return result, nil
}
func markR2OutboxTaskFailed(store r2OutboxTaskStore, task *db.R2DeleteTask, cause error) {
nextRetry := time.Now().Add(r2OutboxBackoff(task.Attempts))
lastError := sanitizeR2OutboxError(cause)
if err := store.MarkFailed(task.ID, nextRetry, lastError); err != nil {
logrus.WithFields(logrus.Fields{
"task_id": task.ID,
"processing_error": lastError,
"persist_error": sanitizeR2OutboxError(err),
}).Warn("R2 outbox 任务失败且重试状态写入失败，任务已保留")
return
}
logrus.WithFields(logrus.Fields{
"task_id": task.ID,
"error": lastError,
"next_retry": nextRetry,
}).Warn("R2 outbox 任务处理失败，已安排重试")
}
func r2OutboxBackoff(attempts int) time.Duration {
if attempts < 0 {
attempts = 0
}
// 1、2、4、8、16、32 分钟后，下一次本应到 64 分钟，直接封顶一小时。
if attempts >= 6 {
return r2OutboxMaxBackoff
}
return r2OutboxInitialBackoff << attempts
}
// sanitizeR2OutboxError 在持久化或记录错误前移除已知配置与凭据，并限制为
// 1024 字节。截断保持 UTF-8 边界，避免向 text 列写入半个多字节字符。
func sanitizeR2OutboxError(err error) string {
if err == nil {
return ""
}
message := err.Error()
sensitiveValues := []string{
conf.Database.DSN,
conf.Database.Password,
conf.Upload.ImageEndpoint,
conf.Upload.ImageAccessID,
conf.Upload.ImageAccessSecret,
conf.Upload.ImageBucket,
conf.Upload.ImageBucketCDNHost,
}
for _, value := range sensitiveValues {
if value != "" {
message = strings.ReplaceAll(message, value, "[redacted]")
}
}
if len(message) <= r2OutboxMaxLastErrorSize {
return message
}
end := r2OutboxMaxLastErrorSize
for end > 0 && !utf8.ValidString(message[:end]) {
end--
}
return message[:end]
}
func r2OutboxConfigured() bool {
return strings.TrimSpace(conf.Upload.ImageEndpoint) != "" &&
strings.TrimSpace(conf.Upload.ImageAccessID) != "" &&
strings.TrimSpace(conf.Upload.ImageAccessSecret) != "" &&
strings.TrimSpace(conf.Upload.ImageBucket) != ""
}
func newR2OutboxObjectDeleter(ctx context.Context) (r2ObjectDeleter, error) {
if !r2OutboxConfigured() {
return nil, errR2OutboxNotConfigured
}
client, err := storage.NewS3Client(
ctx,
conf.Upload.ImageEndpoint,
conf.Upload.ImageBucket,
conf.Upload.ImageAccessID,
conf.Upload.ImageAccessSecret,
)
if err != nil {
return nil, fmt.Errorf("initialize R2 client: %s", sanitizeR2OutboxError(err))
}
return &r2S3ObjectDeleter{client: client}, nil
}
// startR2OutboxWorker 只能在 db.Init 成功后调用。goroutine 由调用方提供的
// WaitGroup 跟踪，Web 退出时先取消 ctx，再等待正在执行的一轮收尾。
func startR2OutboxWorker(ctx context.Context, wg *sync.WaitGroup) {
if !r2OutboxConfigured() {
return
}
deleter, err := newR2OutboxObjectDeleter(ctx)
if err != nil {
logrus.WithField("error", sanitizeR2OutboxError(err)).Warn("R2 outbox worker 启动失败，Web 服务继续运行")
return
}
wg.Add(1)
go func() {
defer wg.Done()
runR2OutboxWorker(ctx, db.R2DeleteTasks, deleter)
}()
}
func runR2OutboxWorker(ctx context.Context, store r2OutboxTaskStore, deleter r2ObjectDeleter) {
ticker := time.NewTicker(r2OutboxWorkerInterval)
defer ticker.Stop()
for {
// 启动先立即跑一轮；处理期间不启动并发轮次。若一轮超过一分钟，
// ticker 只会合并唤醒，不会形成多个 worker 同时消费。
_, err := processR2Outbox(ctx, store, deleter, r2OutboxDefaultLimit)
if err != nil {
if ctx.Err() != nil {
return
}
logrus.WithField("error", sanitizeR2OutboxError(err)).Warn("R2 outbox 本轮处理失败，将在下一分钟重试")
}
select {
case <-ctx.Done():
return
case <-ticker.C:
}
}
}
func drainR2Outbox(ctx context.Context, limit int) (r2OutboxResult, error) {
deleter, err := newR2OutboxObjectDeleter(ctx)
if err != nil {
return r2OutboxResult{}, err
}
return processR2Outbox(ctx, db.R2DeleteTasks, deleter, limit)
}
func runR2Outbox(ctx *cli.Context) error {
limit := ctx.Int("limit")
if limit <= 0 {
return errors.New("--limit must be greater than zero")
}
if err := conf.Init(); err != nil {
return fmt.Errorf("load configuration: %w", err)
}
if !r2OutboxConfigured() {
return errR2OutboxNotConfigured
}
dbType := conf.Database.Type
var dsn string
switch dbType {
case "mysql", "":
dsn = conf.MySQLDsn()
case "postgres":
dsn = conf.PostgresDsn()
default:
return fmt.Errorf("unknown database type: %q", dbType)
}
conf.Database.DSN = dsn
gdb, err := db.Init(dbType, dsn)
if err != nil {
return fmt.Errorf("connect to database: %w", err)
}
if sqlDB, dbErr := gdb.DB(); dbErr == nil {
defer func() {
if err := sqlDB.Close(); err != nil {
logrus.WithField("error", sanitizeR2OutboxError(err)).Warn("关闭数据库连接池失败")
}
}()
}
result, err := drainR2Outbox(ctx.Context, limit)
if err != nil {
return fmt.Errorf("drain R2 outbox: %s", sanitizeR2OutboxError(err))
}
logR2OutboxResult("R2 outbox 本轮处理完成", result)
return nil
}
func logR2OutboxResult(message string, result r2OutboxResult) {
entry := logrus.WithFields(logrus.Fields{
"listed": result.Listed,
"removed": result.Removed,
"object_deletes": result.ObjectsDeleted,
"reference_only": result.ReferenceOnly,
"failed": result.Failed,
"skipped": result.Skipped,
"remaining": result.Remaining,
})
if result.Remaining > 0 {
entry.Warn(message + "，仍有任务待重试或保留")
return
}
entry.Info(message)
}
// drainR2OutboxAfterBan 在封禁事务提交后执行。R2 失败只影响对象清理进度，
// 不向 runBan 返回错误，避免运维误以为需要重新执行不可逆的数据库封禁。
func drainR2OutboxAfterBan(ctx context.Context) {
result, err := drainR2Outbox(ctx, r2OutboxDefaultLimit)
if err != nil {
logrus.WithField("error", sanitizeR2OutboxError(err)).Warn(
"数据库封禁与清理已提交，但 R2 outbox 本轮未能处理；任务仍保留，无需重跑 ban，可稍后运行 r2-outbox",
)
return
}
if result.Remaining > 0 {
logR2OutboxResult("数据库封禁与清理已提交；R2 对象清理将在后续重试，无需重跑 ban", result)
return
}
logR2OutboxResult("数据库封禁与清理已提交；R2 outbox 本轮处理完成", result)
}
internal/cmd/r2_outbox_test.go
-270
View File
@@ -1,270 +0,0 @@
package cmd
import (
"context"
"errors"
"fmt"
"strings"
"testing"
"time"
"github.com/stretchr/testify/require"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/db"
)
type fakeR2OutboxFailure struct {
nextRetry time.Time
lastError string
}
type fakeR2OutboxStore struct {
tasks []*db.R2DeleteTask
references map[string]bool
referenceErrs map[string]error
referenceCalls []string
deleted map[uint]bool
deleteErr error
failures map[uint]fakeR2OutboxFailure
markFailedErr error
}
func newFakeR2OutboxStore(tasks ...*db.R2DeleteTask) *fakeR2OutboxStore {
return &fakeR2OutboxStore{
tasks: tasks,
references: make(map[string]bool),
referenceErrs: make(map[string]error),
deleted: make(map[uint]bool),
failures: make(map[uint]fakeR2OutboxFailure),
}
}
func (s *fakeR2OutboxStore) ListDue(ctx context.Context, limit int) ([]*db.R2DeleteTask, error) {
if err := ctx.Err(); err != nil {
return nil, err
}
tasks := s.tasks
if limit >= 0 && len(tasks) > limit {
tasks = tasks[:limit]
}
return append([]*db.R2DeleteTask(nil), tasks...), nil
}
func (s *fakeR2OutboxStore) Delete(id uint) error {
if s.deleteErr != nil {
return s.deleteErr
}
s.deleted[id] = true
return nil
}
func (s *fakeR2OutboxStore) MarkFailed(id uint, nextRetry time.Time, lastError string) error {
if s.markFailedErr != nil {
return s.markFailedErr
}
s.failures[id] = fakeR2OutboxFailure{nextRetry: nextRetry, lastError: lastError}
return nil
}
func (s *fakeR2OutboxStore) HasReferences(ctx context.Context, _, key string) (bool, error) {
if err := ctx.Err(); err != nil {
return false, err
}
s.referenceCalls = append(s.referenceCalls, key)
return s.references[key], s.referenceErrs[key]
}
type fakeR2DeleteCall struct {
bucket string
key string
}
type fakeR2ObjectDeleter struct {
calls []fakeR2DeleteCall
errs map[string]error
onDelete func(context.Context, string, string) error
}
func (d *fakeR2ObjectDeleter) DeleteObject(ctx context.Context, bucket, key string) error {
d.calls = append(d.calls, fakeR2DeleteCall{bucket: bucket, key: key})
if d.onDelete != nil {
return d.onDelete(ctx, bucket, key)
}
return d.errs[key]
}
type fakeR2HTTPStatusError int
func (e fakeR2HTTPStatusError) Error() string {
return fmt.Sprintf("R2 returned HTTP %d", int(e))
}
func (e fakeR2HTTPStatusError) HTTPStatusCode() int {
return int(e)
}
func setR2OutboxTestConfig(t *testing.T) {
t.Helper()
old := conf.Upload
conf.Upload.ImageEndpoint = "https://r2.example.test"
conf.Upload.ImageAccessID = "test-access-id"
conf.Upload.ImageAccessSecret = "test-secret"
conf.Upload.ImageBucket = "configured-bucket"
conf.Upload.ImageBucketCDNHost = "cdn.example.test"
t.Cleanup(func() {
conf.Upload = old
})
}
func TestProcessR2OutboxSuccessAndNotFound(t *testing.T) {
setR2OutboxTestConfig(t)
for _, tt := range []struct {
name string
deleteErr error
}{
{name: "success"},
{name: "not found is success", deleteErr: fakeR2HTTPStatusError(404)},
} {
t.Run(tt.name, func(t *testing.T) {
first := &db.R2DeleteTask{ID: 1, Bucket: conf.Upload.ImageBucket, Key: "first.webp"}
second := &db.R2DeleteTask{ID: 2, Bucket: conf.Upload.ImageBucket, Key: "second.webp"}
store := newFakeR2OutboxStore(first, second)
deleter := &fakeR2ObjectDeleter{errs: map[string]error{"second.webp": tt.deleteErr}}
result, err := processR2Outbox(context.Background(), store, deleter, 100)
require.NoError(t, err)
require.Equal(t, 2, result.Listed)
require.Equal(t, 2, result.Removed)
require.Equal(t, 2, result.ObjectsDeleted)
require.Zero(t, result.Failed)
require.Zero(t, result.Remaining)
require.Equal(t, []fakeR2DeleteCall{
{bucket: conf.Upload.ImageBucket, key: "first.webp"},
{bucket: conf.Upload.ImageBucket, key: "second.webp"},
}, deleter.calls, "任务必须按 ListDue 顺序串行处理")
require.True(t, store.deleted[first.ID])
require.True(t, store.deleted[second.ID])
require.Empty(t, store.failures)
})
}
}
func TestProcessR2OutboxReferencedTaskDeletesNoObject(t *testing.T) {
setR2OutboxTestConfig(t)
task := &db.R2DeleteTask{ID: 11, Bucket: conf.Upload.ImageBucket, Key: "shared.webp"}
store := newFakeR2OutboxStore(task)
store.references[task.Key] = true
deleter := &fakeR2ObjectDeleter{}
result, err := processR2Outbox(context.Background(), store, deleter, 100)
require.NoError(t, err)
require.Empty(t, deleter.calls, "仍有引用时绝不能调用 R2 删除")
require.True(t, store.deleted[task.ID], "过期任务本身应删除，最后引用移除时会重新入队")
require.Equal(t, 1, result.ReferenceOnly)
require.Equal(t, 1, result.Removed)
require.Zero(t, result.ObjectsDeleted)
require.Zero(t, result.Remaining)
}
func TestProcessR2OutboxReferenceErrorSchedulesRetry(t *testing.T) {
setR2OutboxTestConfig(t)
task := &db.R2DeleteTask{ID: 21, Bucket: conf.Upload.ImageBucket, Key: "unknown.webp"}
store := newFakeR2OutboxStore(task)
store.referenceErrs[task.Key] = errors.New("reference query failed")
deleter := &fakeR2ObjectDeleter{}
before := time.Now()
result, err := processR2Outbox(context.Background(), store, deleter, 100)
require.NoError(t, err)
require.Empty(t, deleter.calls)
require.False(t, store.deleted[task.ID])
require.Contains(t, store.failures, task.ID)
failure := store.failures[task.ID]
require.Equal(t, "reference query failed", failure.lastError)
require.WithinDuration(t, before.Add(time.Minute), failure.nextRetry, 2*time.Second)
require.Equal(t, 1, result.Failed)
require.Equal(t, 1, result.Remaining)
}
func TestProcessR2OutboxDeleteFailureUsesBackoffAndBoundsLastError(t *testing.T) {
setR2OutboxTestConfig(t)
task := &db.R2DeleteTask{ID: 31, Bucket: conf.Upload.ImageBucket, Key: "retry.webp", Attempts: 2}
store := newFakeR2OutboxStore(task)
longErr := fmt.Errorf("delete failed endpoint=%s credential=%s %s",
conf.Upload.ImageEndpoint,
conf.Upload.ImageAccessSecret,
strings.Repeat("x", 1100),
)
deleter := &fakeR2ObjectDeleter{errs: map[string]error{task.Key: longErr}}
before := time.Now()
result, err := processR2Outbox(context.Background(), store, deleter, 100)
require.NoError(t, err)
require.Len(t, deleter.calls, 1)
require.False(t, store.deleted[task.ID])
require.Contains(t, store.failures, task.ID)
failure := store.failures[task.ID]
require.WithinDuration(t, before.Add(4*time.Minute), failure.nextRetry, 2*time.Second)
require.LessOrEqual(t, len(failure.lastError), r2OutboxMaxLastErrorSize)
require.NotContains(t, failure.lastError, conf.Upload.ImageEndpoint)
require.NotContains(t, failure.lastError, conf.Upload.ImageAccessSecret)
require.Equal(t, 1, result.Failed)
require.Equal(t, 1, result.Remaining)
}
func TestProcessR2OutboxBucketMismatchIsRetainedWithoutDeletion(t *testing.T) {
setR2OutboxTestConfig(t)
task := &db.R2DeleteTask{ID: 41, Bucket: "different-bucket", Key: "foreign.webp"}
store := newFakeR2OutboxStore(task)
deleter := &fakeR2ObjectDeleter{}
result, err := processR2Outbox(context.Background(), store, deleter, 100)
require.NoError(t, err)
require.Empty(t, store.referenceCalls, "bucket 不匹配时不应查询当前 bucket 的引用")
require.Empty(t, deleter.calls)
require.Empty(t, store.failures)
require.False(t, store.deleted[task.ID])
require.Equal(t, 1, result.Skipped)
require.Zero(t, result.Failed)
require.Equal(t, 1, result.Remaining)
}
func TestProcessR2OutboxContextCancellationStopsWithoutMarkFailed(t *testing.T) {
setR2OutboxTestConfig(t)
first := &db.R2DeleteTask{ID: 51, Bucket: conf.Upload.ImageBucket, Key: "first.webp"}
second := &db.R2DeleteTask{ID: 52, Bucket: conf.Upload.ImageBucket, Key: "second.webp"}
store := newFakeR2OutboxStore(first, second)
ctx, cancel := context.WithCancel(context.Background())
deleter := &fakeR2ObjectDeleter{
onDelete: func(ctx context.Context, _, _ string) error {
cancel()
return ctx.Err()
},
}
result, err := processR2Outbox(ctx, store, deleter, 100)
require.ErrorIs(t, err, context.Canceled)
require.Len(t, deleter.calls, 1, "取消后不得继续处理第二个任务")
require.Empty(t, store.failures, "优雅关闭导致的取消不应增加任务失败次数")
require.Empty(t, store.deleted)
require.Zero(t, result.Failed)
require.Equal(t, 2, result.Remaining)
}
func TestR2OutboxBackoffCapsAtOneHour(t *testing.T) {
for _, tt := range []struct {
attempts int
expected time.Duration
}{
{attempts: -1, expected: time.Minute},
{attempts: 0, expected: time.Minute},
{attempts: 1, expected: 2 * time.Minute},
{attempts: 2, expected: 4 * time.Minute},
{attempts: 5, expected: 32 * time.Minute},
{attempts: 6, expected: time.Hour},
{attempts: 100, expected: time.Hour},
} {
require.Equal(t, tt.expected, r2OutboxBackoff(tt.attempts))
}
}
internal/cmd/report.go
-551
View File
@@ -1,551 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"context"
"fmt"
"html"
"html/template"
"sort"
"strings"
"time"
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
"github.com/urfave/cli/v2"
"gorm.io/gorm"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/db"
"github.com/tamakyi/TamaBox/internal/mail"
"github.com/tamakyi/TamaBox/internal/security/geoip"
"github.com/tamakyi/TamaBox/internal/security/report"
"github.com/tamakyi/TamaBox/internal/shared"
)
// reportCommand 是 honeypot report 子命令。
var reportCommand = &cli.Command{
Name: "report",
Usage: "Generate a weekly/monthly security summary (map + email)",
Description: "统计周期内的蜜罐命中，把来源 IP 通过公共 IP 库定位到城市，\n" +
" 汇总成带世界地图的报告，并（可选）发送到 security_alert_email。",
Flags: []cli.Flag{
&cli.StringFlag{Name: "period", Value: "week", Usage: "week or month"},
&cli.StringFlag{Name: "to", Usage: "Override recipient (default: honeypot_report_email / security_alert_email)"},
&cli.StringFlag{Name: "dir", Usage: "Output directory (default: honeypot_report_dir)"},
&cli.BoolFlag{Name: "no-email", Usage: "Only generate files, do not send email"},
},
Action: runHoneypotReport,
}
// reportResult 一次生成的产物。
type reportResult struct {
Summary *report.Summary
HTMLPath string
PNGPath string
To string
Sent bool
}
// runHoneypotReport 手动生成/补发一份报告。
//
// 存在的意义不只是「测一下能不能跑」：自动周报发出去以后，运维经常需要
// 「把上周的再发我一份」或「先出一份看看内容对不对」——手动入口必须与
// 自动入口走完全相同的代码路径，否则手动验证过的东西和线上跑的不是一回事。
func runHoneypotReport(ctx *cli.Context) error {
database, err := openDatabase()
if err != nil {
return err
}
now := time.Now()
var period report.Period
switch strings.ToLower(strings.TrimSpace(ctx.String("period"))) {
case "week", "w", "":
period = report.PreviousWeek(now)
case "month", "m":
period = report.PreviousMonth(now)
default:
return errors.Errorf("--period 只能是 week 或 month（收到 %q）", ctx.String("period"))
}
dir := ctx.String("dir")
if dir == "" {
dir = conf.Security.HoneypotReportDir
}
res, err := buildSecurityReport(context.Background(), database, period, dir)
if err != nil {
return err
}
printSecurityReport(res)
if ctx.Bool("no-email") {
fmt.Println()
fmt.Printf("已生成（未发信）：\n %s\n %s\n", res.HTMLPath, res.PNGPath)
return nil
}
to := strings.TrimSpace(ctx.String("to"))
if to == "" {
to = reportRecipient()
}
if to == "" {
return errors.New("未配置收件人：请在 [security] 设置 honeypot_report_email 或 security_alert_email，或用 --to 指定")
}
if err := sendSecurityReport(res, to); err != nil {
return err
}
fmt.Printf("\n已发送到 %s\n", to)
return nil
}
// reportRecipient 返回报告收件人。
//
// 优先 honeypot_report_email，回退 security_alert_email —— 后者早就存在，
// 不给已有部署增加必填项；想分开投递的人再单独配前者。
func reportRecipient() string {
if v := strings.TrimSpace(conf.Security.HoneypotReportEmail); v != "" {
return v
}
return strings.TrimSpace(conf.Security.SecurityAlertEmail)
}
// buildSecurityReport 跑完整的「读数据 → 定位 → 聚合 → 落盘」流程。
func buildSecurityReport(cctx context.Context, database *gorm.DB, period report.Period, dir string) (*reportResult, error) {
store := db.NewHoneypotStore(database)
sources, err := store.AggregateSources(cctx, period.Start, period.End)
if err != nil {
return nil, errors.Wrap(err, "聚合蜜罐来源")
}
paths, err := store.AggregatePaths(cctx, period.Start, period.End, 20)
if err != nil {
return nil, errors.Wrap(err, "聚合被探测路径")
}
stamps, err := store.TimestampsBetween(cctx, period.Start, period.End)
if err != nil {
return nil, errors.Wrap(err, "读取命中时间戳")
}
// 上一周期同为等长窗口，用于「较上期 ↑/↓」。
prevHits, err := countBetween(cctx, store, period.Start.Add(-period.End.Sub(period.Start)), period.Start)
if err != nil {
return nil, errors.Wrap(err, "统计上一周期")
}
// 先按 LimitKey 合并，再只对合并后的键做定位 —— 顺序按命中数降序，
// 因为腾讯精修有配额上限，要优先花在最活跃的来源上。
keys := mergeKeysByHits(sources)
resolver := geoip.New(geoip.Options{
Provider: conf.Security.IPGeoProvider,
TencentKey: conf.Security.IPGeoTencentKey,
})
geo := report.ResolveWithCache(cctx, db.NewIPGeoStore(database), resolver, keys)
sum := report.Build(report.Input{
Period: period,
Sources: sources,
Paths: paths,
Timestamps: stamps,
Geo: geo,
PrevHits: prevHits,
ResolverDesc: resolver.Describe(),
Now: time.Now(),
})
htmlPath, pngPath, err := report.WriteFiles(sum, dir, report.HTMLOptions{
// 报告里的可交互地图用同一个 key（腾讯位置服务）。
TencentMapKey: conf.Security.IPGeoTencentKey,
})
if err != nil {
return nil, errors.Wrap(err, "写报告文件")
}
return &reportResult{Summary: sum, HTMLPath: htmlPath, PNGPath: pngPath}, nil
}
// countBetween 统计 [from, to) 的命中数。
func countBetween(cctx context.Context, store db.HoneypotStore, from, to time.Time) (int64, error) {
after, err := store.CountSince(cctx, from)
if err != nil {
return 0, err
}
upTo, err := store.CountSince(cctx, to)
if err != nil {
return 0, err
}
// CountSince 是「>= since」，两次相减即区间内数量；
// 时钟回拨等异常情况下可能出现负数，钳到 0。
if after < upTo {
return 0, nil
}
return after - upTo, nil
}
// mergeKeysByHits 把来源按封禁口径（LimitKey）合并，返回按命中数降序的键。
func mergeKeysByHits(sources []*db.HoneypotSourceAgg) []string {
hits := make(map[string]int64, len(sources))
for _, s := range sources {
hits[shared.LimitKey(s.IP)] += s.Hits
}
keys := make([]string, 0, len(hits))
for k := range hits {
keys = append(keys, k)
}
// 按命中数降序；同次数按键名升序保证顺序稳定 —— 否则每次跑报告时
// 「腾讯精修覆盖的那 N 个 IP」会随机漂移，两个周期的数据不可比。
sort.Slice(keys, func(i, j int) bool {
if hits[keys[i]] != hits[keys[j]] {
return hits[keys[i]] > hits[keys[j]]
}
return keys[i] < keys[j]
})
return keys
}
// sendSecurityReport 发信（内嵌 PNG 地图 + 附 HTML 报告）。
func sendSecurityReport(res *reportResult, to string) error {
sum := res.Summary
payload := mail.SecurityReportMail{
To: to,
Title: fmt.Sprintf("【狼的提问箱】%s", sum.Period.Title()),
Period: sum.Period.Label(),
Generated: sum.GeneratedAt.Format("2006-01-02 15:04"),
SummaryHTML: template.HTML(buildSummaryHTML(sum)),
CountriesHTML: template.HTML(buildCountriesHTML(sum)),
Notes: template.HTML(buildNotesHTML(sum)),
Attachments: []mail.MailAttachment{{
Path: res.HTMLPath,
Name: sum.Period.Filename() + ".html",
}},
}
// 内嵌地图：只有真的有命中才发（无数据时地图是一张空白经纬网，没有信息量）。
if !sum.Empty && len(sum.Cities) > 0 {
payload.MapCID = "honeypot-map"
payload.InlineImages = []mail.MailInlineImage{{
Path: res.PNGPath,
CID: "honeypot-map",
}}
}
if err := mail.SendSecurityReportMail(payload); err != nil {
return errors.Wrap(err, "发送报告邮件")
}
res.Sent = true
res.To = to
return nil
}
// printSecurityReport 在终端打印报告摘要（手动运行时看）。
func printSecurityReport(res *reportResult) {
sum := res.Summary
fmt.Println(sum.Period.Title())
fmt.Println(strings.Repeat("-", 72))
fmt.Printf(" 窗口：%s\n", sum.Period.Label())
fmt.Printf(" 命中：%d 次（上期 %d）\n", sum.TotalHits, sum.PrevHits)
fmt.Printf(" 独立来源：%d 个，覆盖 %d 个国家/地区\n", sum.UniqueSources, sum.UniqueCountry)
fmt.Printf(" 真实破解尝试：%d 次；已拦截：%d 次\n", sum.CredHits, sum.BannedHits)
if sum.UnlocatedHits > 0 {
fmt.Printf(" 未能定位：%d 次命中（%s）\n", sum.UnlocatedHits, pctOf(sum.UnlocatedHits, sum.TotalHits))
}
if len(sum.Countries) > 0 {
fmt.Println(" 主要来源：")
for i, c := range sum.Countries {
if i >= 8 {
break
}
fmt.Printf(" %-4s %s %6d 次 %s\n", c.Code, padDisplay(truncateForCLI(c.Name, 12), 20), c.Hits, pctOf(c.Hits, sum.TotalHits))
}
}
fmt.Println()
}
// ---- 邮件正文片段 ----
// buildSummaryHTML 生成 KPI 卡片（邮件只能用内联样式，表格布局最稳）。
func buildSummaryHTML(sum *report.Summary) string {
kpis := [][2]string{
{"蜜罐命中", fmt.Sprintf("%d 次", sum.TotalHits)},
{"独立来源", fmt.Sprintf("%d 个", sum.UniqueSources)},
{"涉及国家/地区", fmt.Sprintf("%d 个", sum.UniqueCountry)},
{"真实破解尝试", fmt.Sprintf("%d 次", sum.CredHits)},
{"已拦截", fmt.Sprintf("%d 次", sum.BannedHits)},
{"云主机来源", fmt.Sprintf("%d 个", sum.CloudSources)},
}
var b strings.Builder
b.WriteString(`<table width="100%" border="0" cellspacing="0" cellpadding="0" style="border-collapse:collapse;">`)
for i := 0; i < len(kpis); i += 2 {
b.WriteString(`<tr>`)
for j := i; j < i+2 && j < len(kpis); j++ {
b.WriteString(`<td width="50%" style="padding:6px;">`)
b.WriteString(`<div style="border:1px solid #dadce0;border-radius:8px;padding:12px 14px;">`)
fmt.Fprintf(&b, `<div style="font-size:12px;color:rgba(0,0,0,0.54);">%s</div>`, kpis[j][0])
fmt.Fprintf(&b, `<div style="font-size:20px;font-weight:600;color:#202124;margin-top:2px;">%s</div>`, kpis[j][1])
b.WriteString(`</div></td>`)
}
if i+1 >= len(kpis) {
b.WriteString(`<td width="50%"></td>`)
}
b.WriteString(`</tr>`)
}
b.WriteString(`</table>`)
if sum.PrevHits > 0 {
delta := float64(sum.TotalHits-sum.PrevHits) / float64(sum.PrevHits) * 100
arrow := "上升"
if delta < 0 {
arrow = "下降"
}
fmt.Fprintf(&b, `<div style="font-size:13px;color:rgba(0,0,0,0.6);margin-top:10px;">较上一周期%s %.0f%%（上期 %d 次）。</div>`,
arrow, absFloat(delta), sum.PrevHits)
}
return b.String()
}
// buildCountriesHTML 生成国家排行表。
func buildCountriesHTML(sum *report.Summary) string {
if len(sum.Countries) == 0 {
return ""
}
var b strings.Builder
b.WriteString(`<div style="font-size:13px;color:rgba(0,0,0,0.54);margin-bottom:8px;">来源国家 / 地区（前 10）</div>`)
b.WriteString(`<table width="100%" border="0" cellspacing="0" cellpadding="0" style="border-collapse:collapse;font-size:13px;">`)
b.WriteString(`<tr>`)
for _, h := range []string{"国家/地区", "命中", "占比"} {
align := "left"
if h != "国家/地区" {
align = "right"
}
fmt.Fprintf(&b, `<th align="%s" style="text-align:right;padding:6px 8px;border-bottom:1px solid #dadce0;color:rgba(0,0,0,0.54);font-weight:600;text-align:%s;">%s</th>`,
align, align, h)
}
b.WriteString(`</tr>`)
for i, c := range sum.Countries {
if i >= 10 {
break
}
name := c.Name
if c.Code != "" && c.Code != "--" {
name = fmt.Sprintf("%s（%s）", c.Name, c.Code)
}
fmt.Fprintf(&b, `<tr><td style="padding:6px 8px;border-bottom:1px solid #f1f3f4;color:#202124;">%s</td>`,
html.EscapeString(name))
fmt.Fprintf(&b, `<td align="right" style="padding:6px 8px;border-bottom:1px solid #f1f3f4;text-align:right;color:#202124;">%d</td>`, c.Hits)
fmt.Fprintf(&b, `<td align="right" style="padding:6px 8px;border-bottom:1px solid #f1f3f4;text-align:right;color:rgba(0,0,0,0.6);">%s</td></tr>`,
html.EscapeString(pctOf(c.Hits, sum.TotalHits)))
}
b.WriteString(`</table>`)
return b.String()
}
// buildNotesHTML 生成口径说明。
func buildNotesHTML(sum *report.Summary) string {
lines := []string{
fmt.Sprintf("地理定位数据源：%s。", sum.ResolverDesc),
fmt.Sprintf("未能定位的命中：%d 次（占 %s）。", sum.UnlocatedHits, pctOf(sum.UnlocatedHits, sum.TotalHits)),
"「真实破解尝试」指提交了账号密码字段的请求；捕获到的账号密码不写进报告，只在服务器取证目录中（TamaBox honeypot hits 查看）。",
"「网络归属」来自离线指纹，判定云厂商 / CDN / WAF，与地理位置是两个维度：显示「未识别（普通网络）」不代表没定位到位置。",
}
var b strings.Builder
for _, l := range lines {
fmt.Fprintf(&b, `%s<br/>`, html.EscapeString(l))
}
return b.String()
}
func pctOf(v, total int64) string {
if total <= 0 {
return "—"
}
return fmt.Sprintf("%.1f%%", float64(v)/float64(total)*100)
}
func absFloat(f float64) float64 {
if f < 0 {
return -f
}
return f
}
// ---- 后台调度 ----
// SecurityReportScheduler 周期性检查是否有到期的周报/月报需要发送。
//
// 为什么不直接用 cron：「这一周的周报发过没」需要幂等保证，而幂等只能靠
// 数据库里的台账（security_report_logs 的 period_key 唯一索引）。有了台账，
// 调度器只需要「每半小时看一眼现在该发哪一期、发过没」——
// 服务中途重启、周一维护窗口错过、机器睡了一觉再醒来，都能正确补发。
type SecurityReportScheduler struct {
database *gorm.DB
interval time.Duration
// now 可注入（测试用）。
now func() time.Time
}
// NewSecurityReportScheduler 构造调度器。
func NewSecurityReportScheduler(database *gorm.DB) *SecurityReportScheduler {
return &SecurityReportScheduler{
database: database,
// 30 分钟一轮：周报/月报的时效要求是「周一/月初能看到」，
// 半小时的粒度远够，而且这个检查只读一条台账，成本几乎为零。
interval: 30 * time.Minute,
now: time.Now,
}
}
// Start 启动后台循环，stop 关闭时退出。
func (s *SecurityReportScheduler) Start(stop <-chan struct{}) {
if s == nil || s.database == nil {
return
}
go func() {
// 启动后先等 2 分钟再跑第一轮：让站点先完成启动、DB 连接池预热，
// 也避免与保留期清理抢同一时刻的数据库资源。
select {
case <-stop:
return
case <-time.After(2 * time.Minute):
}
s.tick()
t := time.NewTicker(s.interval)
defer t.Stop()
for {
select {
case <-stop:
return
case <-t.C:
s.tick()
}
}
}()
logrus.WithField("interval", s.interval).Info("安全汇总报告调度器已启动")
}
// tick 检查并发送到期报告。
func (s *SecurityReportScheduler) tick() {
now := s.now()
periods := make([]report.Period, 0, 2)
if conf.Security.HoneypotReportWeekly {
periods = append(periods, report.PreviousWeek(now))
}
if conf.Security.HoneypotReportMonthly {
periods = append(periods, report.PreviousMonth(now))
}
for _, p := range periods {
if !s.due(p, now) {
continue
}
if err := s.deliver(p, now); err != nil {
logrus.WithError(err).WithField("period", p.Key).Warn("安全汇总报告发送失败")
}
}
}
// due 判断某周期现在是否应该发送。
//
// 条件：周期已结束超过 1 小时（留出跨零点写入的余量），且尚未成功发送。
// 不限制「过期多久就不发」：一台停机两周的机器重新上线时，补发上周的周报
// 仍然有意义 —— 反倒是「因为晚了就永远不发」会造成数据黑洞。
func (s *SecurityReportScheduler) due(p report.Period, now time.Time) bool {
if now.Before(p.End) {
return false
}
rec, err := db.NewSecurityReportStore(s.database).Get(context.Background(), p.Key)
if err != nil {
logrus.WithError(err).WithField("period", p.Key).Warn("读取报告台账失败，本轮跳过")
return false
}
if rec == nil {
return true
}
if rec.Sent {
return false
}
// 失败重试上限：SMTP 配错时每次 tick 都失败，无限重试只会把日志和邮箱
// 配额消耗干净。5 次之后停下来，等人工介入（CLI 手动补发会重置计数）。
const maxAttempts = 5
return rec.Attempts < maxAttempts
}
// deliver 生成并发送一份报告，同时写台账。
func (s *SecurityReportScheduler) deliver(p report.Period, now time.Time) error {
store := db.NewSecurityReportStore(s.database)
// 先读一次台账（可能为 nil），用于累计尝试次数。
rec, err := store.Get(context.Background(), p.Key)
if err != nil {
return errors.Wrap(err, "读取台账")
}
if rec == nil {
rec = &db.SecurityReportLog{PeriodKey: p.Key, Kind: p.Kind}
}
rec.WindowStart, rec.WindowEnd = p.Start, p.End
rec.Attempts++
to := reportRecipient()
if to == "" {
rec.Error = "未配置收件人（honeypot_report_email / security_alert_email 均为空）"
_ = store.Save(context.Background(), rec)
return errors.New(rec.Error)
}
rec.Recipient = to
res, err := buildSecurityReport(context.Background(), s.database, p, conf.Security.HoneypotReportDir)
if err != nil {
rec.Error = truncateForCLI(err.Error(), 480)
_ = store.Save(context.Background(), rec)
return err
}
rec.Hits = res.Summary.TotalHits
rec.UniqueSources = int64(res.Summary.UniqueSources)
rec.Banned = res.Summary.BannedHits
rec.Countries = res.Summary.UniqueCountry
rec.FilePath = res.HTMLPath
if err := sendSecurityReport(res, to); err != nil {
rec.Error = truncateForCLI(err.Error(), 480)
_ = store.Save(context.Background(), rec)
return err
}
rec.Sent = true
rec.Error = ""
if err := store.Save(context.Background(), rec); err != nil {
// 台账写失败意味着下一轮会重复发送。这里必须大声报出来，
// 否则用户会收到同一周的周报两三次而不知道原因。
logrus.WithError(err).WithField("period", p.Key).
Error("报告已发送但台账写入失败：下一轮可能重复发送同一期报告")
return nil
}
logrus.WithFields(logrus.Fields{
"period": p.Key, "hits": rec.Hits, "to": to, "file": rec.FilePath,
}).Info("安全汇总报告已发送")
return nil
}
// padDisplay 按「显示列宽」右补空格，让 CLI 表格对齐。
//
// 不能用 %-20s：Go 的宽度按字符数算，一个汉字只算 1，终端里却占两格 ——
// 国家名改成中文之后，表格会歪得看不出哪一列是哪一列。
func padDisplay(s string, width int) string {
w := 0
for _, r := range s {
if r > 0x2E80 {
w += 2
} else {
w++
}
}
if w >= width {
return s
}
return s + strings.Repeat(" ", width-w)
}
internal/cmd/report_test.go
-103
View File
@@ -1,103 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"context"
"testing"
"time"
"github.com/stretchr/testify/require"
"github.com/tamakyi/TamaBox/internal/db"
"github.com/tamakyi/TamaBox/internal/dbutil"
"github.com/tamakyi/TamaBox/internal/security/report"
)
// TestMergeKeysByHits 覆盖「按封禁口径合并后再定位」的键生成。
//
// 顺序很重要：腾讯精修有配额上限，只处理前 N 个 —— 必须优先给最活跃的来源，
// 否则配额会花在只命中一次的长尾地址上，而报告的主要来源反而定位不到。
func TestMergeKeysByHits(t *testing.T) {
rows := []*db.HoneypotSourceAgg{
{IP: "2408:8207:1234:5678::1", Hits: 5},
{IP: "2408:8207:1234:5678::2", Hits: 3}, // 同 /64 → 合成 8
{IP: "203.0.113.7", Hits: 6},
{IP: "198.51.100.1", Hits: 1},
}
got := mergeKeysByHits(rows)
require.Len(t, got, 3)
// 8 次（合并后的 /64）> 6 次 > 1 次
require.Equal(t, "2408:8207:1234:5678::/64", got[0])
require.Equal(t, "203.0.113.7", got[1])
require.Equal(t, "198.51.100.1", got[2])
}
// TestMergeKeysByHitsStable 覆盖同命中数时的稳定排序。
//
// 不稳定的话，每次跑报告被腾讯精修覆盖的那批 IP 会随机漂移，
// 两个周期的定位精度就不一致了，对比起来像是数据变了。
func TestMergeKeysByHitsStable(t *testing.T) {
rows := []*db.HoneypotSourceAgg{
{IP: "203.0.113.9", Hits: 2},
{IP: "203.0.113.2", Hits: 2},
{IP: "203.0.113.5", Hits: 2},
}
first := mergeKeysByHits(rows)
for i := 0; i < 20; i++ {
require.Equal(t, first, mergeKeysByHits(rows), "同命中数时顺序必须稳定")
}
}
// TestSchedulerDue 覆盖周报/月报的发送判定，这是「不重复发、不永远不发」的核心。
func TestSchedulerDue(t *testing.T) {
database, cleanup := dbutil.NewTestDB(t, db.AllTables...)
t.Cleanup(func() {
if err := cleanup("security_report_logs"); err != nil {
t.Fatal(err)
}
})
s := NewSecurityReportScheduler(database)
ctx := context.Background()
loc := time.Local
// now = 2026-10-26（周一）02:00，上一周是 10-19 ~ 10-25
now := time.Date(2026, 10, 26, 2, 0, 0, 0, loc)
period := report.PreviousWeek(now)
require.Equal(t, "week:2026-W43", period.Key)
// 1) 台账里没有记录 → 该发
require.True(t, s.due(period, now))
// 2) 已成功发送 → 不再发（哪怕重启一百次）
store := db.NewSecurityReportStore(database)
require.NoError(t, store.Save(ctx, &db.SecurityReportLog{
PeriodKey: period.Key, Kind: period.Kind,
WindowStart: period.Start, WindowEnd: period.End, Sent: true, Attempts: 1,
}))
require.False(t, s.due(period, now))
// 3) 发送失败但未超重试上限 → 继续重试
require.NoError(t, store.Save(ctx, &db.SecurityReportLog{
PeriodKey: period.Key, Kind: period.Kind,
WindowStart: period.Start, WindowEnd: period.End,
Sent: false, Attempts: 3, Error: "smtp auth failed",
}))
require.True(t, s.due(period, now))
// 4) 超过重试上限 → 停下来等人工介入，避免刷爆日志与邮箱配额
require.NoError(t, store.Save(ctx, &db.SecurityReportLog{
PeriodKey: period.Key, Kind: period.Kind,
WindowStart: period.Start, WindowEnd: period.End,
Sent: false, Attempts: 5, Error: "smtp auth failed",
}))
require.False(t, s.due(period, now))
// 5) 周期还没结束 → 不发（哪怕台账里没有记录）
future := report.PreviousWeek(now.AddDate(0, 0, 7))
require.False(t, s.due(future, now), "窗口未结束时不能发不完整的报告")
}
internal/cmd/restore.go
-123
View File
@@ -1,123 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
"github.com/urfave/cli/v2"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/db"
)
// Restore 恢复被自助停用的账号。
//
// 自助停用（Deactivate）只清空内容、保留用户行作「身份占位」（软删除），
// 因此恢复只需清掉 deleted_at；内容已不可找回。
//
// 用法：TamaBox restore --email [email protected]
//
// TamaBox restore --domain someone --password 'new-password'
var Restore = &cli.Command{
Name: "restore",
Usage: "Restore a deactivated account (clears the identity placeholder)",
Action: runRestore,
Flags: []cli.Flag{
&cli.StringFlag{
Name: "email",
Usage: "Email of the deactivated account",
},
&cli.StringFlag{
Name: "domain",
Usage: "Custom domain of the deactivated account",
},
&cli.StringFlag{
Name: "password",
Usage: "Optional: reset the password to this value (min 8 chars)",
},
&cli.BoolFlag{
Name: "yes",
Usage: "Skip confirmation",
},
},
}
func runRestore(ctx *cli.Context) error {
if err := conf.Init(); err != nil {
return errors.Wrap(err, "load configuration")
}
dbType := conf.Database.Type
if dbType == "postgres" {
conf.Database.DSN = conf.PostgresDsn()
} else {
conf.Database.DSN = conf.MySQLDsn()
}
database, err := db.Init(dbType, conf.Database.DSN)
if err != nil {
return errors.Wrap(err, "connect to database")
}
email := ctx.String("email")
domain := ctx.String("domain")
if email == "" && domain == "" {
return errors.New("must provide --email or --domain")
}
newPassword := ctx.String("password")
if newPassword != "" && len(newPassword) < 8 {
return errors.New("password must be at least 8 characters")
}
// 用 Unscoped 查找：待恢复的账号必然是软删除状态，普通查询看不见
var user db.User
query := database.WithContext(ctx.Context).Unscoped()
if email != "" {
query = query.Where("email = ?", email)
} else {
query = query.Where("domain = ?", domain)
}
if err := query.First(&user).Error; err != nil {
return errors.Wrap(err, "find user to restore")
}
if !user.DeletedAt.Valid {
return errors.Errorf("账号 %q 未被停用，无需恢复", user.Domain)
}
logrus.WithFields(logrus.Fields{
"id": user.ID,
"name": user.Name,
"email": user.Email,
"domain": user.Domain,
}).Warn("准备恢复以下已停用账号（提问/追问/私聊等内容在停用时已被删除，无法找回）")
if !ctx.Bool("yes") {
logrus.Warn("输入大写 YES 确认执行恢复：")
var answer string
if _, err := fmtScan(&answer); err != nil {
return errors.Wrap(err, "read confirmation")
}
if answer != "YES" {
return errors.New("已取消")
}
}
if err := db.Users.Reactivate(ctx.Context, user.ID); err != nil {
return errors.Wrap(err, "reactivate user")
}
// 密码重置必须在恢复之后：UpdatePassword 走普通作用域，软删除状态下找不到该用户
if newPassword != "" {
if err := db.Users.UpdatePassword(ctx.Context, user.ID, newPassword); err != nil {
return errors.Wrap(err, "reset password")
}
logrus.WithField("user_id", user.ID).Info("账号已恢复，密码已重置")
return nil
}
logrus.WithField("user_id", user.ID).Info("账号已恢复（密码未改动，如原主已忘记密码请用 --password 重置）")
return nil
}
internal/cmd/restrict.go
-587
View File
@@ -1,587 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package cmd
import (
"context"
"fmt"
"strings"
"time"
"unicode/utf8"
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
"github.com/urfave/cli/v2"
"gorm.io/gorm"
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/db"
"github.com/tamakyi/TamaBox/internal/i18n"
"github.com/tamakyi/TamaBox/internal/mail"
)
// 本文件提供站方处置能力。项目刻意不做管理后台，因此运营动作全部落在 CLI：
//
// TamaBox reports --domain xxx 出证据包（只读）
// TamaBox restrict --domain xxx --level L1 --days 7 --reason "..."
// TamaBox unrestrict --domain xxx
//
// 处置记录由运行时读表生效（见 db.Restrictions.ActiveLevel），到期自动失效，
// 不需要定时任务，也不需要任何后台页面。
// Restrict 对箱主施加一级处置。
var Restrict = &cli.Command{
Name: "restrict",
Usage: "Restrict a user (L1 stop distribution / L2 narrow publishing / L3 freeze publishing / L4 suspend page)",
Flags: []cli.Flag{
&cli.StringFlag{Name: "email", Usage: "Email of the user"},
&cli.StringFlag{Name: "domain", Usage: "Custom domain of the user"},
&cli.StringFlag{Name: "level", Value: string(db.RestrictionL1), Usage: "Restriction level: L1 / L2 / L3 / L4"},
&cli.IntFlag{Name: "days", Value: 7, Usage: "Effective days, counted from now"},
&cli.StringFlag{Name: "reason", Usage: "Reason recorded for audit (required, not shown to the user)"},
&cli.BoolFlag{Name: "yes", Usage: "Skip confirmation"},
&cli.BoolFlag{Name: "force", Usage: "Required when --days exceeds 90 (abnormal duration)"},
&cli.BoolFlag{Name: "no-notify", Usage: "Do not email the restriction notice to the user"},
},
Action: runRestrict,
}
// Unrestrict 撤销箱主当前生效的全部处置。
var Unrestrict = &cli.Command{
Name: "unrestrict",
Usage: "Revoke all active restrictions of a user",
Flags: []cli.Flag{
&cli.StringFlag{Name: "email", Usage: "Email of the user"},
&cli.StringFlag{Name: "domain", Usage: "Custom domain of the user"},
&cli.BoolFlag{Name: "no-notify", Usage: "Do not email the lift notice to the user"},
},
Action: runUnrestrict,
}
// Reports 输出某箱主的举报证据包，或全站待处理举报列表（只读，不改数据）。
var Reports = &cli.Command{
Name: "reports",
Usage: "Show abuse reports of a user, or list all pending reports",
Flags: []cli.Flag{
&cli.StringFlag{Name: "email", Usage: "Email of the user"},
&cli.StringFlag{Name: "domain", Usage: "Custom domain of the user"},
&cli.IntFlag{Name: "days", Value: 30, Usage: "Only count reports created within N days"},
&cli.IntFlag{Name: "limit", Value: 30, Usage: "Max rows to print"},
&cli.BoolFlag{Name: "pending", Usage: "List all pending reports across the site (ignores --email/--domain)"},
&cli.BoolFlag{Name: "stats", Usage: "Show site-wide report statistics (ignores --email/--domain)"},
},
Action: runReports,
}
// openDatabase 复用 ban / censor 的初始化流程：读配置 → 拼 DSN → 连库并 AutoMigrate。
func openDatabase() (*gorm.DB, error) {
if err := conf.Init(); err != nil {
return nil, errors.Wrap(err, "load configuration")
}
dbType := conf.Database.Type
if dbType == "postgres" {
conf.Database.DSN = conf.PostgresDsn()
} else {
conf.Database.DSN = conf.MySQLDsn()
}
database, err := db.Init(dbType, conf.Database.DSN)
if err != nil {
return nil, errors.Wrap(err, "connect to database")
}
return database, nil
}
// findTargetUser 按 email / domain 定位用户。
// 用 Unscoped 以支持已自助停用（软删除）的账号 —— 处置历史必须能追溯到停用账号。
func findTargetUser(database *gorm.DB, email, domain string) (*db.User, error) {
if email == "" && domain == "" {
return nil, errors.New("must provide --email or --domain")
}
var user db.User
query := database.Unscoped()
if email != "" {
query = query.Where("email = ?", email)
} else {
query = query.Where("domain = ?", domain)
}
if err := query.First(&user).Error; err != nil {
return nil, errors.Wrap(err, "find user")
}
return &user, nil
}
func runRestrict(ctx *cli.Context) error {
level := strings.TrimSpace(ctx.String("level"))
if !db.IsValidRestrictionLevel(level) {
return errors.Errorf("invalid --level %q (want L1 / L2 / L3 / L4)", level)
}
days := ctx.Int("days")
if days <= 0 {
return errors.New("--days must be positive")
}
// 不设硬上限（确实存在长期封禁场景），但超过 90 天必须显式加 --force：
// 这类值几乎都是手误（多打一个 0），靠 --yes 挡不住重复执行的历史命令。
if days > restrictDaysForceThreshold && !ctx.Bool("force") {
return errors.Errorf("--days %d 超过 %d 天，属于异常时长；确认无误请加 --force 重试",
days, restrictDaysForceThreshold)
}
reason := strings.TrimSpace(ctx.String("reason"))
if reason == "" {
return errors.New("--reason is required (recorded for audit)")
}
database, err := openDatabase()
if err != nil {
return err
}
user, err := findTargetUser(database, ctx.String("email"), ctx.String("domain"))
if err != nil {
return err
}
activeLevel, active, err := db.NewRestrictionsStore(database).ActiveLevel(ctx.Context, user.ID)
if err != nil {
return errors.Wrap(err, "query active restriction")
}
fmt.Printf("箱主: %s (@%s) id=%d\n", user.Name, user.Domain, user.ID)
if activeLevel != "" {
// active 理论上不会为 nil（有级别就有记录），但脏数据/并发下宁可少打一行也不要 panic。
until, reason := "-", "-"
if active != nil {
until = active.ExpiresAt.Format("2006-01-02 15:04")
reason = active.Reason
}
fmt.Printf("当前处置: %s（至 %s，原因：%s）→ 本次将替换该记录\n", activeLevel, until, reason)
} else {
fmt.Println("当前处置: 无")
}
fmt.Printf("本次处置: %s，%d 天，原因：%s\n", level, days, reason)
if days > restrictDaysForceThreshold {
fmt.Printf("⚠️ 超长处置：%d 天，到期 %s（常规处置为 7–30 天）\n",
days, time.Now().AddDate(0, 0, days).Format("2006-01-02 15:04"))
}
// 二次确认：异常时长时，即使已给 --force，交互模式下还要再输入一次级别。
// 脚本里 `--force --yes` 两个显式开关本身就是两次确认，不再额外拦截。
if days > restrictDaysForceThreshold && !ctx.Bool("yes") {
logrus.Warn("这是超长处置。请再次输入级别名（如 L3）确认：")
var confirmLevel string
if _, err := fmtScan(&confirmLevel); err != nil {
return errors.Wrap(err, "read confirmation")
}
if strings.TrimSpace(confirmLevel) != level {
return errors.New("已取消（级别不匹配）")
}
}
if !ctx.Bool("yes") {
logrus.Warn("输入大写 YES 确认执行（该操作可经 unrestrict 撤销）：")
var answer string
if _, err := fmtScan(&answer); err != nil {
return errors.Wrap(err, "read confirmation")
}
if answer != "YES" {
return errors.New("已取消")
}
}
restriction, err := db.NewRestrictionsStore(database).Create(ctx.Context, db.CreateRestrictionOptions{
UserID: user.ID,
Level: level,
Reason: reason,
CreatedBy: "cli",
Days: days,
})
if err != nil {
return errors.Wrap(err, "create restriction")
}
logrus.WithFields(logrus.Fields{
"user_id": user.ID,
"level": level,
"expires_at": restriction.ExpiresAt,
}).Info("处置已生效")
fmt.Printf("已生效，到期时间 %s（到期自动解除，无需手工操作）\n",
restriction.ExpiresAt.Format("2006-01-02 15:04"))
if !ctx.Bool("no-notify") {
notifyRestrictionOwner(user, level, restriction.ExpiresAt)
}
return nil
}
// restrictDaysForceThreshold 超过这个天数需要 --force。不做硬上限：长期封禁是真实需求。
const restrictDaysForceThreshold = 90
// notifyRestrictionOwner 把处置结果通知箱主（按他自己的界面语言）。
//
// 为什么必须通知：处置是平台单方面限制用户功能，不告知就变成「暗箱」，
// 用户既无法自查也无法申诉。邮件里只给「级别 + 到期时间 + 规则链接」，
// 不引用 --reason（那是运维审计备注），也不引用被举报内容原文。
//
// 发送失败只告警、不回滚：处置已经写入，邮件不可用不应让运营者误以为没生效。
func notifyRestrictionOwner(user *db.User, level string, expires time.Time) {
if user.Email == "" {
fmt.Println("（该账号没有邮箱，跳过处置通知）")
return
}
lang := user.Language
if lang == "" {
lang = conf.App.DefaultLang
}
levelDesc := i18n.T(lang, "restriction.level."+level)
notice := mail.RestrictionNotice{
To: user.Email,
Heading: i18n.T(lang, "mail.restriction.heading"),
Greeting: i18n.T(lang, "mail.restriction.greeting", user.Name),
Body: i18n.T(lang, "mail.restriction.body", user.Domain, level, levelDesc, expires.Format("2006-01-02 15:04")),
Note: i18n.T(lang, "mail.restriction.note"),
RulesText: i18n.T(lang, "mail.restriction.rules"),
RulesURL: strings.TrimRight(conf.App.ExternalURL, "/") + "/rules",
Appeal: i18n.T(lang, "mail.restriction.appeal"),
}
reportNoticeResult(user, sendNotice(notice), "处置已生效")
}
// notifyRestrictionLifted 告知箱主「限制已解除」。
//
// 与处置通知同等重要：只通知「你被罚了」而不通知「已经解除」，用户会一直以为还在限制里，
// 既不敢发内容，也可能反复来问。这封信也顺带说明「私密内容不会自动恢复」——
// 否则他会以为解禁后一切照旧。
func notifyRestrictionLifted(user *db.User, level string) {
if user.Email == "" {
fmt.Println("（该账号没有邮箱，跳过解除通知）")
return
}
lang := user.Language
if lang == "" {
lang = conf.App.DefaultLang
}
levelDesc := i18n.T(lang, "restriction.level."+level)
notice := mail.RestrictionNotice{
To: user.Email,
Heading: i18n.T(lang, "mail.unrestrict.heading"),
Greeting: i18n.T(lang, "mail.restriction.greeting", user.Name),
Body: i18n.T(lang, "mail.unrestrict.body", user.Domain, levelDesc),
Note: i18n.T(lang, "mail.unrestrict.note"),
RulesText: i18n.T(lang, "mail.restriction.rules"),
RulesURL: strings.TrimRight(conf.App.ExternalURL, "/") + "/rules",
// 解除通知不需要申诉入口（Appeal 留空，模板会整段省略）。
}
reportNoticeResult(user, sendNotice(notice), "解除已生效")
}
// sendNotice 发送一封通知邮件，带 20 秒超时。
//
// 为什么要超时：gomail 这版没有 Timeout 字段，裸 Dial 会一直等到系统 TCP 超时（可达两分钟），
// 运营者站在终端前会以为命令卡死。通知失败不影响已经写入的处置结果。
func sendNotice(notice mail.RestrictionNotice) error {
done := make(chan error, 1)
go func() { done <- mail.SendRestrictionNoticeMail(notice) }()
select {
case err := <-done:
return err
case <-time.After(20 * time.Second):
return errors.New("发送通知邮件超时")
}
}
// reportNoticeResult 统一输出通知结果（成功/失败都不影响已生效的处置）。
func reportNoticeResult(user *db.User, err error, action string) {
if err != nil {
logrus.WithError(err).WithField("user_id", user.ID).Warn("通知邮件发送失败（" + action + "）")
fmt.Printf("⚠️ 通知邮件发送失败（%s）。请检查 [mail] 配置，或用 --no-notify 跳过通知。\n", action)
return
}
lang := user.Language
if lang == "" {
lang = conf.App.DefaultLang
}
fmt.Printf("已发送通知邮件至 %s（语言 %s）\n", user.Email, i18n.Resolve(lang))
}
func runUnrestrict(ctx *cli.Context) error {
database, err := openDatabase()
if err != nil {
return err
}
user, err := findTargetUser(database, ctx.String("email"), ctx.String("domain"))
if err != nil {
return err
}
store := db.NewRestrictionsStore(database)
// 先取级别：撤销之后就读不到了，而通知邮件需要写明解除的是哪一级。
level, _, err := store.ActiveLevel(ctx.Context, user.ID)
if err != nil {
return errors.Wrap(err, "query active restriction")
}
affected, err := store.RevokeActive(ctx.Context, user.ID)
if err != nil {
return errors.Wrap(err, "revoke restrictions")
}
fmt.Printf("箱主: %s (@%s) id=%d\n", user.Name, user.Domain, user.ID)
if affected == 0 {
fmt.Println("没有生效中的处置，无需操作")
return nil
}
logrus.WithFields(logrus.Fields{"user_id": user.ID, "count": affected, "level": level}).Info("已撤销处置")
fmt.Printf("已撤销 %d 条生效中的处置\n", affected)
if !ctx.Bool("no-notify") && level != "" {
notifyRestrictionLifted(user, string(level))
}
return nil
}
// reportedQuestionRow 证据包里的一行：被举报的提问及其举报数。
type reportedQuestionRow struct {
ID uint
Content string
CreatedAt time.Time
ReportCount int64
PendingCount int64 // 其中仍为 pending 的条数（已处理的举报仍保留在证据里）
}
// pendingReportRow 全站待处理举报的一行（按箱主聚合展示）。
type pendingReportRow struct {
Domain string
QuestionID uint
Content string
ReportCount int64
LastAt time.Time
}
func runReports(ctx *cli.Context) error {
database, err := openDatabase()
if err != nil {
return err
}
if ctx.Bool("stats") {
return printReportStats(ctx.Context, database, ctx.Int("days"))
}
if ctx.Bool("pending") {
return printPendingReports(ctx.Context, database, ctx.Int("limit"))
}
return printUserReport(database, ctx)
}
func printUserReport(database *gorm.DB, ctx *cli.Context) error {
user, err := findTargetUser(database, ctx.String("email"), ctx.String("domain"))
if err != nil {
return err
}
days := ctx.Int("days")
if days <= 0 {
days = 30
}
since := time.Now().AddDate(0, 0, -days)
fmt.Printf("箱主: %s (@%s) id=%d\n", user.Name, user.Domain, user.ID)
fmt.Println(strings.Repeat("-", 60))
store := db.NewRestrictionsStore(database)
level, active, err := store.ActiveLevel(ctx.Context, user.ID)
if err != nil {
return errors.Wrap(err, "query active restriction")
}
if level == "" {
fmt.Println("当前处置: 无")
} else {
until, reason := "-", "-"
if active != nil {
until = active.ExpiresAt.Format("2006-01-02 15:04")
reason = active.Reason
}
fmt.Printf("当前处置: %s（至 %s，原因：%s）\n", level, until, reason)
}
// 公开回答总数：用于计算「被举报内容占其公开产出」的比例，
// 这是判断「组织化挂人」与「偶发吐槽」最直接的一个量。
var publicAnswered int64
if err := database.WithContext(ctx.Context).
Model(&db.Question{}).
Where("user_id = ? AND answer != '' AND is_private = false", user.ID).
Count(&publicAnswered).Error; err != nil {
return errors.Wrap(err, "count public answered questions")
}
var rows []*reportedQuestionRow
if err := database.WithContext(ctx.Context).
Raw(`SELECT q.id AS id, q.content AS content, q.created_at AS created_at,
COUNT(r.id) AS report_count,
SUM(CASE WHEN r.status = ? THEN 1 ELSE 0 END) AS pending_count
FROM questions q
JOIN content_reports r ON r.question_id = q.id
WHERE q.user_id = ? AND q.deleted_at IS NULL AND r.created_at >= ?
GROUP BY q.id, q.content, q.created_at
ORDER BY report_count DESC, q.created_at DESC
LIMIT ?`, db.ReportStatusPending, user.ID, since, ctx.Int("limit")).Scan(&rows).Error; err != nil {
return errors.Wrap(err, "query reported questions")
}
var totalReports, totalPending int64
for _, row := range rows {
totalReports += row.ReportCount
totalPending += row.PendingCount
}
// 比例的分母是「公开回答总数」，分子必须是「被举报的条目数」——
// ⚠️ 不能拿举报次数当分子：同一条内容可被多人举报，次数可以超过条目数，
// 实测会出现 166.7% 这种无意义的数值（5 次举报 / 3 条回答）。
ratio := 0.0
if publicAnswered > 0 {
ratio = float64(len(rows)) / float64(publicAnswered) * 100
}
// 分母是「当前累计公开回答」，不是窗口内的产出 —— 文案必须写清「累计」，
// 否则读者会以为分子分母同窗口（实测箱主被 L2 收窄后分母骤降，比例会超过 100%）。
fmt.Printf("近 %d 天: 被举报 %d 条 / 公开回答 %d 条（累计，%.1f%%）；举报 %d 次，其中待处理 %d 次\n",
days, len(rows), publicAnswered, ratio, totalReports, totalPending)
if len(rows) == 0 {
fmt.Println("没有举报记录")
} else {
fmt.Println("被举报条目（按举报数降序）:")
for _, row := range rows {
// 明确区分「总举报」与「仍待处理」：箱主处理过内容后举报会自动变 accepted，
// 只报总数会让人误以为还有 3 条挂着。
state := "已处理"
if row.PendingCount > 0 {
state = fmt.Sprintf("待处理 %d", row.PendingCount)
}
fmt.Printf(" 举报 %-3d #%-6d %s %s（%s）\n",
row.ReportCount, row.ID, row.CreatedAt.Format("2006-01-02 15:04"),
truncateForCLI(row.Content, 48), state)
}
}
history, err := store.ListByUserID(ctx.Context, user.ID)
if err != nil {
return errors.Wrap(err, "list restriction history")
}
fmt.Println(strings.Repeat("-", 60))
if len(history) == 0 {
fmt.Println("历史处置: 无")
return nil
}
fmt.Println("历史处置:")
for _, item := range history {
state := "生效中"
if item.RevokedAt != nil {
state = "已撤销 " + item.RevokedAt.Format("2006-01-02")
} else if item.ExpiresAt.Before(time.Now()) {
state = "已到期"
}
fmt.Printf(" %s %s 至 %s %s（%s）\n",
item.CreatedAt.Format("2006-01-02 15:04"), item.Level,
item.ExpiresAt.Format("2006-01-02"), item.Reason, state)
}
return nil
}
func printPendingReports(ctx context.Context, database *gorm.DB, limit int) error {
if limit <= 0 {
limit = 30
}
var rows []*pendingReportRow
if err := database.WithContext(ctx).
Raw(`SELECT u.domain AS domain, q.id AS question_id, q.content AS content,
COUNT(r.id) AS report_count, MAX(r.created_at) AS last_at
FROM content_reports r
JOIN questions q ON q.id = r.question_id
JOIN users u ON u.id = q.user_id
WHERE r.status = ? AND q.deleted_at IS NULL
GROUP BY u.domain, q.id, q.content
ORDER BY u.domain, report_count DESC, last_at DESC
LIMIT ?`, db.ReportStatusPending, limit).Scan(&rows).Error; err != nil {
return errors.Wrap(err, "query pending reports")
}
if len(rows) == 0 {
fmt.Println("没有待处理的举报")
return nil
}
fmt.Printf("待处理举报 %d 条（按举报数降序）:\n", len(rows))
lastDomain := ""
for _, row := range rows {
if row.Domain != lastDomain {
fmt.Printf("\n@%s\n", row.Domain)
lastDomain = row.Domain
}
fmt.Printf(" 举报 %-3d #%-6d %s %s\n",
row.ReportCount, row.QuestionID, row.LastAt.Format("2006-01-02 15:04"),
truncateForCLI(row.Content, 48))
}
return nil
}
// printReportStats 输出全站维度的举报统计。
//
// 这是「举报是否被武器化」的唯一观测手段：正常举报是分散的，组织化举报会表现为
// 同一批 IP 集中打同一批箱主。没有这个视图，运营者只能一个 domain 一个 domain 地猜。
func printReportStats(ctx context.Context, database *gorm.DB, days int) error {
if days <= 0 {
days = 7
}
since := time.Now().AddDate(0, 0, -days)
store := db.NewReportsStore(database)
users, err := store.TopReportedUsers(ctx, since, 10)
if err != nil {
return errors.Wrap(err, "query top reported users")
}
reporters, err := store.TopReporters(ctx, since, 10)
if err != nil {
return errors.Wrap(err, "query top reporters")
}
fmt.Printf("统计窗口：近 %d 天（仅待处理举报；待处理最长回溯 %d 天）\n", days, 30)
fmt.Println(strings.Repeat("-", 60))
fmt.Println("被举报最多的箱主：")
if len(users) == 0 {
fmt.Println(" 无")
}
for i, u := range users {
fmt.Printf(" %2d. @%-20s %-14s %d 条\n", i+1, u.Domain, u.Name, u.Count)
}
fmt.Println()
fmt.Println("举报来源 IP 最多：")
if len(reporters) == 0 {
fmt.Println(" 无")
}
for i, r := range reporters {
fmt.Printf(" %2d. %-18s %d 次\n", i+1, r.ReporterIP, r.Count)
}
fmt.Println()
fmt.Println("提示：同一 IP 集中举报同一批内容，或某箱主举报数远高于其他箱主时，")
fmt.Println(" 先判断是组织化挂人还是举报被武器化，再决定是否处置。")
return nil
}
// truncateForCLI 按 rune 截断并压平换行，避免终端输出被长内容冲散。
func truncateForCLI(s string, max int) string {
s = strings.ReplaceAll(strings.ReplaceAll(s, "\r", " "), "\n", " ")
if utf8.RuneCountInString(s) <= max {
return s
}
runes := []rune(s)
return string(runes[:max]) + "..."
}
internal/cmd/web.go
+5 -150
View File
@@ -5,13 +5,8 @@
package cmd
import (
"context"
"fmt"
"net/http"
"os"
"os/signal"
"sync"
"syscall"
"time"
"github.com/pkg/errors"
@@ -22,13 +17,9 @@ import (
"github.com/tamakyi/TamaBox/internal/conf"
"github.com/tamakyi/TamaBox/internal/db"
"github.com/tamakyi/TamaBox/internal/insights"
"github.com/tamakyi/TamaBox/internal/route"
"github.com/tamakyi/TamaBox/internal/security/honeypot"
"github.com/tamakyi/TamaBox/internal/shared"
"github.com/tamakyi/TamaBox/internal/stats"
"github.com/tamakyi/TamaBox/internal/tracing"
"github.com/tamakyi/TamaBox/route/question"
)
var Web = &cli.Command{
@@ -76,118 +67,25 @@ func runWeb(ctx *cli.Context) error {
}
conf.Database.DSN = dsn
gdb, err := db.Init(dbType, dsn)
_, err := db.Init(dbType, dsn)
if err != nil {
return errors.Wrap(err, "connect to database")
}
// 退出前把连接池关掉，避免优雅关闭期间连接还在池里挂着。
if sqlDB, dbErr := gdb.DB(); dbErr == nil {
defer func() {
if err := sqlDB.Close(); err != nil {
logrus.WithError(err).Warn("关闭数据库连接池失败")
}
}()
}
// 蜜罐命中记录保留期清理：honeypot_hits 是只追加的审计表，写入完全由
// 外部扫描流量驱动（不可预期、不可节流）。没有自动清理的话，表体积只增不减。
// 保留期复用 honeypot_retain_days（与 CLI prune 同一个口径），开关为 honeypot_auto_clean。
//
// 凭据文件（明文账号密码）也按同一个保留期清理 —— 它们不该比元数据活得更久。
// 这里独立打开一次目录即可：PurgeBefore 只删「整天都早于保留期」的文件，
// 与 route 层那个 Append 用的句柄不会争抢同一天的文件。
// 两个后台任务（保留期清理 / 周期报告）共用一个停止信号，
// defer 必须放在 if 外面 —— 否则「自动清理关掉、报告开着」时这个
// channel 永远不会被关闭，那个 goroutine 就一直挂着。
stopRetention := make(chan struct{})
defer close(stopRetention)
if conf.Security.HoneypotAutoClean {
var credPurge db.CredPurgeable
if cs, err := honeypot.NewFileCredStore(conf.Security.HoneypotCredDir); err != nil {
logrus.WithError(err).Warn("蜜罐凭据目录不可用，凭据文件将不会被自动清理")
} else {
credPurge = cs
}
db.NewHoneypotRetention(db.Honeypots, credPurge, conf.Security.HoneypotRetainDays, conf.Security.HoneypotMaxRows, 0).Start(stopRetention)
}
// 周期安全汇总（周报 / 月报）：把命中按 IP 定位到城市，出地图报告并邮件送达。
// 幂等靠 security_report_logs 的 period_key 唯一索引，所以这里只管定期看一眼
// 「该发的那期发过没」—— 重启、错过时间窗都能正确补发，也不会重复发。
if conf.Security.HoneypotReportEnabled {
if reportRecipient() == "" {
logrus.Warn("已启用安全汇总报告，但 honeypot_report_email 与 security_alert_email 都为空，将无法送达")
}
NewSecurityReportScheduler(gdb).Start(stopRetention)
}
// Redis 配了就必须连得上：session 建在它上面，宕机等于全站 500（含匿名访客）。
// 启动期 fail fast，别让运维在「站点全 500」的现场去猜是不是 Redis。
if conf.Redis.Addr != "" {
if err := shared.PingRedis(conf.Redis.Addr, conf.Redis.Password); err != nil {
return errors.Wrapf(err,
"无法连接 Redis（%s）。session 依赖它，连不上会导致全站 500，启动已中止。"+
"请检查 [redis] addr/password，或清空 addr 改用进程内 session 与缓存",
conf.Redis.Addr)
}
logrus.WithField("addr", conf.Redis.Addr).Info("Redis 连接正常")
} else {
logrus.Info("未配置 [redis] addr：session 与缓存均使用进程内实现（单副本部署可用）")
}
logrus.WithContext(ctx.Context).WithField("external_url", conf.App.ExternalURL).Info("Starting web server")
// 箱主数据面板的访问记录器：异步批量写 box_views，不阻塞页面渲染。
// 密钥复用 server.xsrf_key —— 它已经是启动期强校验过的非空随机串，
// 而且与 CSRF token 的用途不同（这里只做 HMAC 的一次性密钥），不存在混用风险。
insightsStore := db.BoxViews
if insightsStore != nil {
insights.Views = insights.NewRecorder(insightsStore, conf.Server.XSRFKey)
defer insights.Views.Close()
insights.StartMaintenance(ctx.Context, insightsStore)
}
// 站点默认语言初始化（default_lang 配置，未配置时回退 zh-CN）
shared.App.SetLang(conf.App.DefaultLang)
// 分享卡字体：缺字体只会在「第一张分享图被请求」时暴露成 500，而 /share-card 是公开端点。
// 启动时先探一次（顺带把读文件 + 解析的开销挪出请求路径），缺了直接 WARN 并给出补救办法。
if fontPath, err := question.CheckShareCardFont(); err != nil {
logrus.WithError(err).Warn("分享卡字体不可用，/share-card 将返回 500：" +
"装一个 glyf 轮廓的 CJK 字体（apt install fonts-wqy-zenhei）" +
"或把 ttf/otf/ttc 放进 static/fonts/，也可用 [app] font_path 指定")
} else {
logrus.WithField("font", fontPath).Info("分享卡字体已就绪")
}
r := route.New()
r.Use(tracing.Middleware("TamaBox"))
// 全站数据页预热：整页聚合是若干次全表 GROUP BY，若摊在当天第一个访客身上，
// 首屏要白等一秒以上。这里延后几秒在后台先算一次，把等待挪出请求路径。
// 失败只告警：页面在真正被访问时会自己重算并（若仍失败）回退到上一次成功的结果。
go func() {
time.Sleep(3 * time.Second)
if _, err := stats.OverviewData(ctx.Context); err != nil {
logrus.WithError(err).Warn("预热全站统计数据失败")
}
}()
// 最外层挂载 gzip 压缩，并在 http.Server 上配置超时：
// - ReadHeaderTimeout 防止慢速客户端占用连接（slowloris 的防线在这里）
// - ReadHeaderTimeout 防止慢速客户端占用连接
// - ReadTimeout / WriteTimeout 防止读写挂死
// - IdleTimeout 复用 keep-alive 连接
// listen 留空时回退到 ":port"（监听所有网卡）；Cloudflare Tunnel 部署建议设为
// "127.0.0.1:<port>"，使源站端口仅对本地 cloudflared 可见，即使防火墙误配也无法被外部直连。
//
// ReadTimeout 从 30s 提到 120s：站内允许单图 8MB（storage.MaxUploadBytes），
// 请求体上限 12MB（form.MaxRequestBodySize）。30s 传完 8MB 需要 ≥273 KB/s 上行，
// 而手机 4G 上行常在 1–2 Mbps（125–250 KB/s）—— 一张 8MB 图必然超时，且用户
// 已经写好的提问正文会一起丢掉（POST 失败不回填）。120s 对应约 68 KB/s，
// 偏远地区 3G 也能过。
//
// 放宽 ReadTimeout 不会让 slowloris 重新变得可行：那类攻击卡在「发不完 header」，
// 由 10s 的 ReadHeaderTimeout 拦住；ReadTimeout 只影响读完 header 之后传 body 的时长。
addr := conf.Server.Listen
if addr == "" {
addr = fmt.Sprintf(":%d", conf.Server.Port)
@@ -196,57 +94,14 @@ func runWeb(ctx *cli.Context) error {
Addr: addr,
Handler: route.GzipHandler(r),
ReadHeaderTimeout: 10 * time.Second,
ReadTimeout: 120 * time.Second,
ReadTimeout: 30 * time.Second,
WriteTimeout: 60 * time.Second,
IdleTimeout: 120 * time.Second,
}
logrus.WithContext(ctx.Context).WithField("port", conf.Server.Port).Info("Listening on")
// 优雅关闭：收到 SIGTERM / SIGINT 后停止接受新连接，给在途请求最多 15 秒收尾。
//
// 改动前是直接 ListenAndServe：Go 对 SIGTERM 的处理就是立即退出进程，
// 于是每次部署 / 重启都会把正在写库的 POST 就地处死，留下
// 「提问已 INSERT、图片还没传完」「回答已写入、配额还没扣」这类半成品。
// systemd Restart=always 与 docker restart 都救不了这个。
runCtx, stop := signal.NotifyContext(ctx.Context, syscall.SIGTERM, os.Interrupt)
var r2WorkerWG sync.WaitGroup
defer func() {
// 先取消 worker 的 context，再等待当前一轮退出，避免无人等待的后台删除。
stop()
r2WorkerWG.Wait()
}()
// db.Init 已成功；R2 未完整配置时此函数直接返回，不影响 Web 启动。
startR2OutboxWorker(runCtx, &r2WorkerWG)
serveErr := make(chan error, 1)
go func() {
err := server.ListenAndServe()
if errors.Is(err, http.ErrServerClosed) {
// 正常的 Shutdown 路径，不算失败
err = nil
}
serveErr <- err
}()
select {
case err := <-serveErr:
// 端口被占 / 监听失败：没有在途请求要收尾，直接返回。
if err != nil {
return errors.Wrap(err, "start http server")
}
return nil
case <-runCtx.Done():
logrus.Info("收到退出信号，正在优雅关闭（最多 15 秒）")
if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
return errors.Wrap(err, "start http server")
}
shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()
if err := server.Shutdown(shutdownCtx); err != nil {
logrus.WithError(err).Warn("优雅关闭超时，强制断开剩余连接")
_ = server.Close()
}
logrus.Info("HTTP 服务已关闭")
return nil
}
internal/conf/announcement.go
-214
View File
@@ -1,214 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package conf
import (
"strings"
"time"
// 容器镜像通常不带 tzdata，import 这个包会把一份时区库编进二进制，
// LoadLocation("Asia/Shanghai") 才不会因为找不到 zoneinfo 而失败。
_ "time/tzdata"
"github.com/sirupsen/logrus"
"github.com/tamakyi/TamaBox/internal/i18n"
)
// defaultAnnouncementZone 裸时间（不带偏移）的默认解释时区。
// 站点面向中文用户，运维写「10-25 02:00」时心里想的是北京时间，
// 而容器里的 time.Local 是 UTC —— 默认按东八区解释可以避免整体偏移 8 小时。
const defaultAnnouncementZone = "Asia/Shanghai"
// announcementConfig 站内公告（[announcement] 段）。
//
// 文案留空即关闭公告；Start / End 留空表示该侧不限。
// 展示窗口是左闭右开 [Start, End)：到 end 那一刻公告消失，
// 运维不必为了「准时下线」把时间掐到秒后还担心多挂一分钟。
type announcementConfig struct {
// Content 是默认文案，也是分语言文案缺失时的回退。
Content string `ini:"content"`
ContentZhCN string `ini:"content_zh_cn"`
ContentZhTW string `ini:"content_zh_tw"`
ContentEn string `ini:"content_en"`
ContentJa string `ini:"content_ja"`
Start string `ini:"start"`
End string `ini:"end"`
// Timezone 解释裸时间用的时区名，留空取 defaultAnnouncementZone。
Timezone string `ini:"timezone"`
// 解析后的时间点，零值表示该侧不限。
// ini tag 为 "-"：既不参与 ini 解析，也不会被未知键检测登记为合法键名。
StartAt time.Time `ini:"-"`
EndAt time.Time `ini:"-"`
loc *time.Location `ini:"-"`
}
// Active 判断给定时刻是否处于公告展示窗口，并返回该语言的正文。
// 窗口为左闭右开 [Start, End)，两侧留空表示不限。
func (a announcementConfig) Active(now time.Time, lang string) (string, bool) {
content := a.contentFor(lang)
if content == "" || !a.inWindow(now) {
return "", false
}
return content, true
}
// contentFor 按语言取文案；该语言没配就回退到 Content。
// Content 也没配则返回空 —— 即「没翻译的语言不显示」，而不是硬塞一门语言。
func (a announcementConfig) contentFor(lang string) string {
switch i18n.Resolve(lang) {
case i18n.LangZhCN:
if a.ContentZhCN != "" {
return a.ContentZhCN
}
case i18n.LangZhTW:
if a.ContentZhTW != "" {
return a.ContentZhTW
}
case i18n.LangEn:
if a.ContentEn != "" {
return a.ContentEn
}
case i18n.LangJa:
if a.ContentJa != "" {
return a.ContentJa
}
}
return a.Content
}
// inWindow 只判断时间窗，不看语言 —— 启动日志要知道「现在到点了吗」。
func (a announcementConfig) inWindow(now time.Time) bool {
if !a.StartAt.IsZero() && now.Before(a.StartAt) {
return false
}
if !a.EndAt.IsZero() && !now.Before(a.EndAt) {
return false
}
return true
}
// hasContent 报告是否配了任何语言的文案。
// 只看 Content 会误判「只写了英文文案」为未配置，进而把整条公告关掉。
func (a announcementConfig) hasContent() bool {
return a.Content != "" || a.ContentZhCN != "" || a.ContentZhTW != "" ||
a.ContentEn != "" || a.ContentJa != ""
}
// configuredLanguages 列出真正配了文案的语言，供启动日志核对。
func (a announcementConfig) configuredLanguages() []string {
var langs []string
if a.Content != "" {
langs = append(langs, "fallback")
}
for _, l := range []struct{ code, content string }{
{i18n.LangZhCN, a.ContentZhCN},
{i18n.LangZhTW, a.ContentZhTW},
{i18n.LangEn, a.ContentEn},
{i18n.LangJa, a.ContentJa},
} {
if l.content != "" {
langs = append(langs, l.code)
}
}
return langs
}
// 支持的时间格式。裸时间（不带时区偏移）按 [announcement] timezone 解释。
var announcementTimeLayouts = []string{
"2006-01-02 15:04",
"2006-01-02 15:04:05",
"2006-01-02",
time.RFC3339,
}
// sanitizeAnnouncement 解析公告时间窗。
//
// 时间写错只告警并关闭公告，不阻断启动：公告是展示性配置，拼错一个日期不该让整站
// 502；但必须留下能定位的日志 —— 否则现象就是「配了却不显示」，和未知键被静默
// 忽略属于同一类坑（见 unknown.go）。
func sanitizeAnnouncement() {
Announcement.Content = strings.TrimSpace(Announcement.Content)
Announcement.ContentZhCN = strings.TrimSpace(Announcement.ContentZhCN)
Announcement.ContentZhTW = strings.TrimSpace(Announcement.ContentZhTW)
Announcement.ContentEn = strings.TrimSpace(Announcement.ContentEn)
Announcement.ContentJa = strings.TrimSpace(Announcement.ContentJa)
if !Announcement.hasContent() {
return
}
disable := func(key, value, reason string) {
logrus.WithFields(logrus.Fields{
"section": "announcement",
"key": key,
"value": value,
"reason": reason,
}).Warn("公告配置无效，已关闭公告（站点其它功能不受影响）")
Announcement = announcementConfig{}
}
loc, err := loadAnnouncementLocation(Announcement.Timezone)
if err != nil {
disable("timezone", Announcement.Timezone, "不是合法的 IANA 时区名（如 Asia/Shanghai / UTC）")
return
}
Announcement.loc = loc
var ok bool
if Announcement.StartAt, ok = parseAnnouncementTime(Announcement.Start, loc); !ok {
disable("start", Announcement.Start, "支持 2006-01-02 15:04 / 2006-01-02 15:04:05 / 2006-01-02 / RFC3339")
return
}
if Announcement.EndAt, ok = parseAnnouncementTime(Announcement.End, loc); !ok {
disable("end", Announcement.End, "支持 2006-01-02 15:04 / 2006-01-02 15:04:05 / 2006-01-02 / RFC3339")
return
}
if !Announcement.StartAt.IsZero() && !Announcement.EndAt.IsZero() && !Announcement.EndAt.After(Announcement.StartAt) {
disable("end", Announcement.End, "end 必须晚于 start，否则公告永远不会展示")
return
}
logrus.WithFields(logrus.Fields{
"zone": loc.String(),
"languages": strings.Join(Announcement.configuredLanguages(), ","),
"start": announcementBoundLabel(Announcement.StartAt),
"end": announcementBoundLabel(Announcement.EndAt),
"active_now": Announcement.inWindow(time.Now()),
}).Info("站内公告已配置")
}
// loadAnnouncementLocation 解析时区名；空值取默认时区（东八区）。
func loadAnnouncementLocation(name string) (*time.Location, error) {
name = strings.TrimSpace(name)
if name == "" {
name = defaultAnnouncementZone
}
return time.LoadLocation(name)
}
// parseAnnouncementTime 解析单个时间点；空串返回零值（表示不限）且视为合法。
// 带偏移的 RFC3339 以自带偏移为准，loc 只用于裸时间。
func parseAnnouncementTime(raw string, loc *time.Location) (time.Time, bool) {
raw = strings.TrimSpace(raw)
if raw == "" {
return time.Time{}, true
}
for _, layout := range announcementTimeLayouts {
if t, err := time.ParseInLocation(layout, raw, loc); err == nil {
return t, true
}
}
return time.Time{}, false
}
// announcementBoundLabel 把时间点格式化成带时区偏移的字符串，供启动日志核对
// 「我写的 10:00 到底被当成了几点」—— 裸时间按 [announcement] timezone 解释。
func announcementBoundLabel(t time.Time) string {
if t.IsZero() {
return "不限"
}
return t.Format("2006-01-02 15:04:05 -07:00")
}
internal/conf/announcement_test.go
-243
View File
@@ -1,243 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package conf
import (
"testing"
"time"
"github.com/tamakyi/TamaBox/internal/i18n"
)
// setAnnouncement 在测试期间覆盖全局公告配置，结束后恢复。
// 不设 Timezone，即走默认的东八区。
func setAnnouncement(t *testing.T, content, start, end string) {
t.Helper()
old := Announcement
t.Cleanup(func() { Announcement = old })
Announcement = announcementConfig{Content: content, Start: start, End: end}
sanitizeAnnouncement()
}
// setAnnouncementConfig 用完整配置覆盖，供分语言 / 时区用例使用。
func setAnnouncementConfig(t *testing.T, cfg announcementConfig) {
t.Helper()
old := Announcement
t.Cleanup(func() { Announcement = old })
Announcement = cfg
sanitizeAnnouncement()
}
func mustParseIn(t *testing.T, layout, value string) time.Time {
t.Helper()
loc, err := time.LoadLocation(defaultAnnouncementZone)
if err != nil {
t.Fatalf("load zone %s: %v", defaultAnnouncementZone, err)
}
parsed, err := time.ParseInLocation(layout, value, loc)
if err != nil {
t.Fatalf("parse %q: %v", value, err)
}
return parsed
}
func TestAnnouncementDisabledWhenContentEmpty(t *testing.T) {
setAnnouncement(t, " ", "2026-10-24 00:00", "2026-10-26 00:00")
if _, ok := Announcement.Active(time.Now(), i18n.LangZhCN); ok {
t.Fatal("所有语言文案都为空时公告应关闭")
}
}
func TestAnnouncementWindowIsHalfOpen(t *testing.T) {
setAnnouncement(t, "维护通知", "2026-10-24 00:00", "2026-10-26 00:00")
start := mustParseIn(t, "2006-01-02 15:04", "2026-10-24 00:00")
end := mustParseIn(t, "2006-01-02 15:04", "2026-10-26 00:00")
cases := []struct {
name string
now time.Time
want bool
}{
{"开始前一秒", start.Add(-time.Second), false},
{"开始时刻（闭区间）", start, true},
{"窗口内", start.Add(12 * time.Hour), true},
{"结束时刻（开区间）", end, false},
{"结束后", end.Add(time.Hour), false},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
content, ok := Announcement.Active(c.now, i18n.LangZhCN)
if ok != c.want {
t.Fatalf("Active(%s) = %v, want %v", c.now, ok, c.want)
}
if ok && content != "维护通知" {
t.Fatalf("content = %q, want 维护通知", content)
}
})
}
}
// 只写一侧的边界必须保持「该侧不限」，不能因为另一侧为空就整体失效。
func TestAnnouncementOneSidedWindow(t *testing.T) {
now := mustParseIn(t, "2006-01-02 15:04", "2026-10-22 12:00")
setAnnouncement(t, "只有开始", "2026-10-23 00:00", "")
if _, ok := Announcement.Active(now, i18n.LangZhCN); ok {
t.Fatal("只写 start 且尚未到点时应不展示")
}
if _, ok := Announcement.Active(now.Add(48*time.Hour), i18n.LangZhCN); !ok {
t.Fatal("只写 start 时到点后应一直展示")
}
setAnnouncement(t, "只有结束", "", "2026-10-23 00:00")
if _, ok := Announcement.Active(now, i18n.LangZhCN); !ok {
t.Fatal("只写 end 且未到点时应立即展示")
}
if _, ok := Announcement.Active(now.Add(48*time.Hour), i18n.LangZhCN); ok {
t.Fatal("只写 end 时过点后应下线")
}
setAnnouncement(t, "一直展示", "", "")
if _, ok := Announcement.Active(now.AddDate(5, 0, 0), i18n.LangZhCN); !ok {
t.Fatal("起止都留空时应一直展示")
}
}
// 分语言文案：配了就用自己的，没配回退 content；content 也没配则该语言不显示。
func TestAnnouncementLanguageSelection(t *testing.T) {
setAnnouncementConfig(t, announcementConfig{
Content: "fallback",
ContentZhCN: "简中",
ContentEn: "english",
ContentJa: "日本語",
})
cases := []struct{ lang, want string }{
{i18n.LangZhCN, "简中"},
{i18n.LangEn, "english"},
{i18n.LangJa, "日本語"},
{i18n.LangZhTW, "fallback"}, // 没配繁中 → 回退默认文案
{"en-US", "english"}, // Resolve 会归一化
}
for _, c := range cases {
got, ok := Announcement.Active(time.Now(), c.lang)
if !ok || got != c.want {
t.Fatalf("Active(lang=%s) = %q ok=%v, want %q", c.lang, got, ok, c.want)
}
}
// 只配英文、content 留空：简中访客不应看到英文公告。
setAnnouncementConfig(t, announcementConfig{ContentEn: "english only"})
if _, ok := Announcement.Active(time.Now(), i18n.LangZhCN); ok {
t.Fatal("该语言未配文案且无默认文案时不应展示")
}
if got, ok := Announcement.Active(time.Now(), i18n.LangEn); !ok || got != "english only" {
t.Fatalf("英文应正常展示，got %q ok=%v", got, ok)
}
}
func TestAnnouncementTimeFormats(t *testing.T) {
loc, err := time.LoadLocation(defaultAnnouncementZone)
if err != nil {
t.Fatalf("load zone: %v", err)
}
// 带偏移的 RFC3339 必须按字面时刻解析，而不是再套一层默认时区。
at, ok := parseAnnouncementTime("2026-10-25T02:00:00+08:00", loc)
if !ok {
t.Fatal("RFC3339 应可解析")
}
want := time.Date(2026, 10, 24, 18, 0, 0, 0, time.UTC)
if !at.Equal(want) {
t.Fatalf("解析结果 = %s, want %s", at.UTC(), want)
}
if at, ok := parseAnnouncementTime("2026-10-25", loc); !ok || at.Hour() != 0 {
t.Fatalf("纯日期应解析为当天 00:00，got %s ok=%v", at, ok)
}
if at, ok := parseAnnouncementTime("2026-10-25 02:00:59", loc); !ok || at.Second() != 59 {
t.Fatalf("秒级格式应可解析，got %s ok=%v", at, ok)
}
if _, ok := parseAnnouncementTime("2026/10/25 02:00", loc); ok {
t.Fatal("错误格式应解析失败")
}
if _, ok := parseAnnouncementTime("2026-13-01", loc); ok {
t.Fatal("非法月份应解析失败")
}
}
// 裸时间必须按东八区解释：运维写「10-25 02:00」指北京时间，
// 而容器里的 time.Local 是 UTC（旧实现整体偏 8 小时）。
func TestAnnouncementBareTimeUsesBeijing(t *testing.T) {
setAnnouncement(t, "维护通知", "2026-10-25 02:00", "")
want := time.Date(2026, 10, 24, 18, 0, 0, 0, time.UTC) // 北京 10-25 02:00
if !Announcement.StartAt.Equal(want) {
t.Fatalf("裸时间应按 +08:00 解释，got %s, want %s", Announcement.StartAt.UTC(), want)
}
if _, offset := Announcement.StartAt.Zone(); offset != 8*60*60 {
t.Fatalf("解析后的偏移 = %d 秒, want 28800", offset)
}
}
// timezone 显式指定时以它为准，不能继续套东八区。
func TestAnnouncementTimezoneOverride(t *testing.T) {
setAnnouncementConfig(t, announcementConfig{
Content: "维护通知",
Start: "2026-10-25 00:00",
Timezone: "UTC",
})
want := time.Date(2026, 10, 25, 0, 0, 0, 0, time.UTC)
if !Announcement.StartAt.Equal(want) {
t.Fatalf("timezone=UTC 时应按 UTC 解析，got %s", Announcement.StartAt.UTC())
}
setAnnouncementConfig(t, announcementConfig{
Content: "维护通知",
Start: "2026-10-25 00:00",
Timezone: "America/New_York",
})
// 纽约 10-25 00:00 = UTC 10-25 04:00（EDT，UTC-4）
wantNY := time.Date(2026, 10, 25, 4, 0, 0, 0, time.UTC)
if !Announcement.StartAt.Equal(wantNY) {
t.Fatalf("timezone=America/New_York 解析错误，got %s", Announcement.StartAt.UTC())
}
}
// 时区名写错和日期写错一样：只关公告，不阻断启动。
func TestAnnouncementInvalidTimezoneDisables(t *testing.T) {
setAnnouncementConfig(t, announcementConfig{
Content: "维护通知",
Start: "2026-10-25 00:00",
Timezone: "Mars/Olympus",
})
if Announcement.Content != "" {
t.Fatal("时区无效时公告应被关闭")
}
}
// 时间写错只关公告，不能让站点起不来；同时必须清空解析结果，避免残留时间窗。
func TestAnnouncementInvalidTimeDisables(t *testing.T) {
for _, c := range []struct{ name, start, end string }{
{"start 格式错", "2026/10/25 02:00", ""},
{"end 格式错", "", "10月26日"},
{"end 早于 start", "2026-10-26 00:00", "2026-10-25 00:00"},
{"end 等于 start", "2026-10-25 00:00", "2026-10-25 00:00"},
} {
t.Run(c.name, func(t *testing.T) {
setAnnouncement(t, "内容", c.start, c.end)
if Announcement.Content != "" {
t.Fatal("配置无效时公告应被关闭")
}
if !Announcement.StartAt.IsZero() || !Announcement.EndAt.IsZero() {
t.Fatal("配置无效时应清空已解析的时间点")
}
})
}
}
internal/conf/conf.go
+1 -60
View File
@@ -12,7 +12,7 @@ import (
"gopkg.in/ini.v1"
)
// File 是解析后的配置对象。
// File is the configuration object.
var File *ini.File
func Init() error {
@@ -29,10 +29,6 @@ func Init() error {
return errors.Wrapf(err, "parse %q", configFile)
}
// 键名归一化必须在 MapTo **之前**做：ini 对未知键是静默忽略的，
// 等 MapTo 跑完，错拼的键早就被丢掉了，再也认不出来。
normalizeAllSectionKeys(File)
if err := File.Section("app").MapTo(&App); err != nil {
return errors.Wrap(err, "map 'server'")
}
@@ -46,14 +42,6 @@ func Init() error {
return errors.Wrap(err, "map 'security'")
}
// 蜜罐配置归一化：把「未配置」与「显式关闭」区分开，回退安全默认值。
sanitizeHoneypot()
if err := validateTextCensorSource(Security.EnableTextCensor, Security.TextCensorSource,
App.QiniuAccessKey, App.QiniuAccessSecret, App.AliyunAccessKey, App.AliyunAccessKeySecret); err != nil {
return err
}
if err := File.Section("server").MapTo(&Server); err != nil {
return errors.Wrap(err, "map 'server'")
}
@@ -96,25 +84,10 @@ func Init() error {
// ini 键留空会被 int 解析为 0；<1 的值一律回退内置默认，防止上限被静默置零。
sanitizeLimits(&Limits)
// 主题：默认 slug 与启用清单。段缺失时 MapTo 得到空值，运行期回退内置 default，
// 因此老配置文件不写 [theme] 也能正常启动。
if err := File.Section("theme").MapTo(&Theme); err != nil {
return errors.Wrap(err, "map 'theme'")
}
if err := File.Section("announcement").MapTo(&Announcement); err != nil {
return errors.Wrap(err, "map 'announcement'")
}
sanitizeAnnouncement()
if err := File.Section("mail").MapTo(&Mail); err != nil {
return errors.Wrap(err, "map 'mail'")
}
if err := File.Section("notify").MapTo(&Notify); err != nil {
return errors.Wrap(err, "map 'notify'")
}
serviceSections := File.Section("service").ChildSections()
for _, serviceSection := range serviceSections {
serviceSection := serviceSection
@@ -130,35 +103,3 @@ func Init() error {
return nil
}
// validateTextCensorSource 校验文本审核通道（[security] text_censor_source）与凭据的搭配。
// 抽成纯函数（只依赖入参、不读全局）以便单测覆盖，也让 Init 保持轻薄。
//
// - 审核整体关闭（enabled=false）→ 不校验，不需要任何凭据。
// - 留空 / auto → 通过。auto 是历史默认（七牛优先、阿里云兜底），两者都无凭据时
// 维持既有运行期 fail-closed 行为，不阻断启动（否则 app.sample.ini 原样拷贝无法启动）。
// - 显式选 qiniu / aliyun → 必须配齐该通道凭据，否则启动即失败：缺凭据时运行期审核必失败，
// 而审核失败是 fail-closed（拒绝提交），会让发布/私信整站不可用且现象隐蔽。
// - 其它取值 → 直接报错，不做静默回退：拼写错误若被当成 auto，运维会误以为已切通道。
func validateTextCensorSource(enabled bool, source, qiniuKey, qiniuSecret, aliyunKey, aliyunSecret string) error {
if !enabled {
return nil
}
switch strings.ToLower(strings.TrimSpace(source)) {
case "", CensorSourceAuto:
return nil
case CensorSourceQiniu:
if qiniuKey == "" || qiniuSecret == "" {
return errors.New("security.text_censor_source = qiniu requires app.qiniu_access_key and app.qiniu_access_secret")
}
return nil
case CensorSourceAliyun:
if aliyunKey == "" || aliyunSecret == "" {
return errors.New("security.text_censor_source = aliyun requires app.aliyun_access_key and app.aliyun_access_key_secret")
}
return nil
default:
return errors.Errorf("security.text_censor_source must be one of qiniu / aliyun / auto, got %q", source)
}
}
internal/conf/honeypot_defaults.go
-140
View File
@@ -1,140 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package conf
import (
"strings"
"github.com/sirupsen/logrus"
)
// 蜜罐相关配置的默认值。
//
// 为什么要显式兜底：ini 的 MapTo 在「键缺失」或「值非法」时**不覆盖**目标字段，
// 所以结构体的零值就是「未配置」的表现。而零值对这几个开关恰好是最危险的那个：
//
// - HoneypotAutoClean 零值 false → 未配置的站点自动清理是关的，
// honeypot_hits 只增不减；
// - HoneypotRetainDays 零值 0 → 保留期 0 天 = 永不清理；
// - HoneypotMaxRows 零值 0 → 无行数上限。
//
// 现场就踩过这个坑：配置写成了 honeypot_retention_days（多一个 t），
// 键名不匹配被 ini 静默忽略，保留期成了 0，自动清理形同关闭。
const (
// DefaultHoneypotRetainDays 蜜罐记录默认保留天数。
DefaultHoneypotRetainDays = 30
// DefaultHoneypotMaxRows 蜜罐记录默认行数上限。
// 实测单行约 281 字节（含索引，常规 UA），20 万行约 53 MB。
DefaultHoneypotMaxRows = 200000
// DefaultHoneypotThreshold 「提交凭据」多少次即封禁。默认 1：
// 往假后台里填账号密码是证据最强的行为，抓到一次就足够。
// 纯路径探测不走这个阈值（见 route.honeypotHandler.Serve）。
DefaultHoneypotThreshold = 1
// DefaultHoneypotBanMinutes 蜜罐封禁的默认时长（分钟）。
//
// 刻意远长于常规 ban_duration_minutes（15 分钟）：蜜罐命中的不是「访问了一个
// 可疑路径」，而是「往假后台里填了账号密码」—— 对方已经付出破解成本、
// 且拿到了一次响应（知道「后台存在」）。15 分钟不足以让对方放弃，
// 24 小时能覆盖一轮扫描活动周期。
DefaultHoneypotBanMinutes = 1440
// DefaultHoneypotCredDir 凭据取证文件的默认目录（相对进程工作目录）。
//
// 不放在数据库所在目录：这两者的权限、备份策略、留存周期都应该分开管。
DefaultHoneypotCredDir = "data/honeypot-creds"
// DefaultIPGeoProvider 默认的地理定位数据源：auto（ip-api 打底 + 腾讯精修）。
DefaultIPGeoProvider = "auto"
// DefaultHoneypotReportDir 安全汇总报告文件的默认目录。
//
// 与凭据目录分开：报告里有攻击者 IP 明细，但它是可以外发/归档的材料；
// 凭据目录里是明文账号密码，永不外发。放在一起容易误打包。
DefaultHoneypotReportDir = "data/reports"
)
// sanitizeHoneypot 归一化蜜罐相关配置，修正「未配置」与「显式关闭」的歧义。
//
// 语义约定（两个开关各管一件事，不再互相牵连）：
//
// honeypot_auto_clean 是否启用后台自动清理。缺省 true（开）。
// honeypot_retain_days 保留多少天。缺省 30 天。
//
// 也就是说：**要关闭自动清理请写 honeypot_auto_clean = false**，
// 而不要靠把 retain_days 写成 0 —— 保留 0 天意味着「记录一进来就删」，
// 既不是任何人的真实意图，也会让「自动清理到底开没开」变得无法判断。
//
// 显式写 honeypot_max_rows = 0 仍表示「不设行数上限」（这是明确的逃生口），
// 但会告警提醒：没有时间闸也没有数量闸的表只增不减。
func sanitizeHoneypot() {
sec := File.Section("security")
hasRetain := sec.HasKey("honeypot_retain_days")
hasMaxRows := sec.HasKey("honeypot_max_rows")
// 保留期：未配置或显式 <= 0 → 回退默认。
// 显式 0 的语义是「立刻删除」，与「不自动清理」混淆，判为误配。
if !hasRetain {
Security.HoneypotRetainDays = DefaultHoneypotRetainDays
} else if Security.HoneypotRetainDays <= 0 {
logrus.WithField("default", DefaultHoneypotRetainDays).
Warn("honeypot_retain_days <= 0 已被忽略，改用默认值（如需关闭自动清理请设 honeypot_auto_clean = false）")
Security.HoneypotRetainDays = DefaultHoneypotRetainDays
}
// 行数上限：未配置 → 默认；显式 0 → 不设上限（逃生口，但告警）。
if !hasMaxRows {
Security.HoneypotMaxRows = DefaultHoneypotMaxRows
} else if Security.HoneypotMaxRows <= 0 {
logrus.Warn("honeypot_max_rows = 0 表示不设行数上限：蜜罐表将只增不减，请确认这是有意为之")
}
// 自动清理：缺省开启。
// 判据用 HasKey 而不是值 —— 因为 ini 对 bool 的解析是「有键才赋值」，
// 缺键时零值 false 会让「未配置」与「显式关闭」无法区分。
// 显式 false 是合法的关闭意图，予以尊重（与 retain_days 的处理不同）。
if !sec.HasKey("honeypot_auto_clean") {
Security.HoneypotAutoClean = true
}
// 封禁阈值：缺省 1。
if !sec.HasKey("honeypot_threshold") {
Security.HoneypotThreshold = DefaultHoneypotThreshold
}
// 封禁时长：缺省 24 小时（见 DefaultHoneypotBanMinutes 的理由）。
// 显式写 <= 0 是逃生口：交给 autoban 回退到 ban_duration_minutes，
// 但那样「蜜罐按常规时长封」的意图不明显，故明确告警。
if !sec.HasKey("honeypot_ban_minutes") {
Security.HoneypotBanMinutes = DefaultHoneypotBanMinutes
} else if Security.HoneypotBanMinutes <= 0 {
logrus.WithField("fallback_key", "ban_duration_minutes").
Warn("honeypot_ban_minutes <= 0 已忽略，蜜罐封禁将回退为 ban_duration_minutes")
}
// 凭据文件目录：未配置或留空都用默认值。
// 这里不回退「不保存」——用户显式开启蜜罐就是想要取证，
// 目录写错会在 route 层触发「不可用 → 不保存凭据」的告警，而不是静默丢弃。
if strings.TrimSpace(Security.HoneypotCredDir) == "" {
Security.HoneypotCredDir = DefaultHoneypotCredDir
}
// 地理定位数据源：未配置 → auto。
// 显式写了不认识的值时保持原样，由 geoip 层解析并告警 ——
// 在配置层悄悄改成 auto 会让人以为配置生效了。
if strings.TrimSpace(Security.IPGeoProvider) == "" {
Security.IPGeoProvider = DefaultIPGeoProvider
}
// 周期报告：三个开关都用 HasKey 判定缺省值（同 HoneypotAutoClean 的理由）。
if !sec.HasKey("honeypot_report_enabled") {
Security.HoneypotReportEnabled = true
}
if !sec.HasKey("honeypot_report_weekly") {
Security.HoneypotReportWeekly = true
}
if !sec.HasKey("honeypot_report_monthly") {
Security.HoneypotReportMonthly = true
}
if strings.TrimSpace(Security.HoneypotReportDir) == "" {
Security.HoneypotReportDir = DefaultHoneypotReportDir
}
}
internal/conf/keynorm.go
-263
View File
@@ -1,263 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package conf
import (
"reflect"
"strings"
"github.com/sirupsen/logrus"
"gopkg.in/ini.v1"
)
// 配置键名归一化：容忍运维手写时的常见失误，避免「配了但不生效」。
//
// 背景：ini 库对未知键是**静默忽略**的 —— 写错一个字母，程序照常启动、
// 照常跑，但那个配置根本没生效，现场还看不出来。本次就踩了这个坑：
// 写 `honeypot_retention_days`（多一个 t）而代码读 `honeypot_retain_days`，
// 表现为「自动清理未启用」警告，而根因是键名不匹配。
//
// 这里做两层兜底：
//
// 1. 键名归一化（normalizeKeyName）：修剪首尾空白、剥掉尾随的
// `<` `>` `=` 等比较符号残留（`honeypot_retention_days <= 30` 会被 ini
// 解析成键名 "honeypot_retention_days <"，不是我们想要的键名）。
// 2. 别名表（keyAliases）：把已知的常见误拼映射到正确键名。
//
// 归一化只影响**键名**，不改动值。且归一化后的键名必须在该段的合法键名
// 白名单内才会被采用 —— 避免把真正写错、无法识别的键「猜」成某个配置项。
// keyAliases 常见误拼 → 正确键名。
//
// 只收录「意图明确、写法唯一」的误拼。收录标准：
// - 去掉别名后一定是该段某个合法键名（由调用方用白名单校验）；
// - 不会与任何合法键名或彼此产生歧义。
//
// 收录历史教训：honeypot_retain_days 被写成 honeypot_retention_days。
var keyAliases = map[string]string{
"honeypot_retention_days": "honeypot_retain_days",
"honeypot_retain_day": "honeypot_retain_days",
"honeypot_retention": "honeypot_retain_days",
"honeypot_maxrow": "honeypot_max_rows",
"honeypot_max_row": "honeypot_max_rows",
"honeypot_maxrow_count": "honeypot_max_rows",
"honeypot_autoclean": "honeypot_auto_clean",
"honeypot_auto_cleaning": "honeypot_auto_clean",
"enable_honeypot_hit": "enable_honeypot",
"honeypot_retaindays": "honeypot_retain_days",
"honeypot_retentionday": "honeypot_retain_days",
"honeypot_keep_days": "honeypot_retain_days",
"honeypot_retain_max_days": "honeypot_retain_days",
// 地理定位与周期报告：这几个键都是新增的，最容易被写成不同的词。
"ipgeo_provider": "ip_geo_provider",
"ip_geolocation_provider": "ip_geo_provider",
"geo_provider": "ip_geo_provider",
"ip_geo_key": "ip_geo_tencent_key",
"ip_geo_tencent_apikey": "ip_geo_tencent_key",
"tencent_map_key": "ip_geo_tencent_key",
"honeypot_report": "honeypot_report_enabled",
"honeypot_report_mail": "honeypot_report_email",
"honeypot_report_to": "honeypot_report_email",
"honeypot_reports_dir": "honeypot_report_dir",
"honeypot_report_path": "honeypot_report_dir",
}
// normalizeKeyName 归一化配置键名。
//
// 处理两类问题：
// 1. 首尾空白与尾随比较符号残留。
// `honeypot_retention_days <= 30` 在 ini 里被解析为键名
// "honeypot_retention_days <"（值 "30"）—— 键名带了尾随的 "<"，
// 直接与任何配置项都对不上。剥掉这些字符后才是用户真正想写的名字。
// 2. 常见误拼别名（见 keyAliases）。
//
// 大小写不归一：ini 的键名匹配本来就是大小写敏感的，
// 顺手转小写反而会让「键名写错大小写」这类问题更难发现。
func normalizeKeyName(raw string) string {
name := strings.TrimSpace(raw)
// 剥掉尾随的空白与比较符号残留（可能叠加多个，如 "key <=" 或 "key =="）。
for len(name) > 0 {
last := name[len(name)-1]
if last == ' ' || last == '\t' || last == '<' || last == '>' || last == '=' {
name = name[:len(name)-1]
continue
}
break
}
// 剥完后可能又暴露出新的尾随空白，继续削。
name = strings.TrimSpace(name)
if name == "" {
return ""
}
// 别名映射（只做一次，不递归，避免别名链产生意外结果）。
if canonical, ok := keyAliases[name]; ok {
return canonical
}
return name
}
// legalKeysOf 收集一个段在代码中真实存在的合法键名。
//
// 通过反射读取结构体的 `ini` tag —— 单一事实来源，避免「白名单与代码脱节」
// 导致新增配置项后被误报为未知键。
//
// 返回的键名集合同时包含 ini tag 原文与其归一化形式（归一化形式一般等于原文，
// 因为 tag 本身不带空白与比较符号）。
func legalKeysOf(v interface{}) map[string]bool {
legal := map[string]bool{}
add := func(name string) {
if name == "" || name == "-" {
return
}
legal[name] = true
}
collect := func(v interface{}) {
rv := reflect.ValueOf(v)
for rv.Kind() == reflect.Ptr {
rv = rv.Elem()
}
if rv.Kind() != reflect.Struct {
return
}
rt := rv.Type()
for i := 0; i < rt.NumField(); i++ {
field := rt.Field(i)
tag := field.Tag.Get("ini")
if tag == "-" {
continue
}
// ini tag 形如 "name" 或 "name,opt1,opt2"，取第一段。
name := tag
if idx := strings.Index(tag, ","); idx >= 0 {
name = tag[:idx]
}
if name == "" {
// 无 ini tag 时 ini 用字段名（小写化后的 snake_case 近似），
// 保守起见不登记 —— 未登记只会导致漏报，不会误报。
continue
}
add(name)
add(normalizeKeyName(name))
}
}
collect(v)
return legal
}
// sectionKeySets 配置文件中各段 → 该段代码里真实存在的合法键名。
//
// 由反射从结构体 ini tag 得出，是单一事实来源：新增配置项后自动纳入，
// 不会出现「白名单与代码脱节」导致的误报。
//
// 注意：ini 对**无 ini tag** 的字段用字段名做键名，这部分无法通过 tag
// 枚举，为避免误报这里不登记（漏报优于误报）。
func sectionKeySets() map[string]map[string]bool {
return map[string]map[string]bool{
"app": legalKeysOf(&App),
"theme": legalKeysOf(&Theme),
"announcement": legalKeysOf(&Announcement),
"security": legalKeysOf(&Security),
"server": legalKeysOf(&Server),
"database": legalKeysOf(&Database),
"redis": legalKeysOf(&Redis),
"recaptcha": legalKeysOf(&Recaptcha),
"pixel": legalKeysOf(&Pixel),
"upload": legalKeysOf(&Upload),
"limits": legalKeysOf(&Limits),
"mail": legalKeysOf(&Mail),
"service": legalKeysOf(&Service),
}
}
// normalizeAllSectionKeys 归一化配置文件中所有段的键名，并告警未知键。
//
// 做两件事：
// 1. 把可识别的误拼键名（带尾随垃圾字符 / 命中别名表）改写成正确键名，
// 改写会记 INFO 日志，便于运维确认「我配的到底生效了没」。
// 2. 把无法识别的键名 WARN 出来（附最接近的合法键名建议）。
// 这是防住「配了但不生效」的关键 —— ini 本身对未知键完全静默。
//
// 只告警不报错：未知键不应该阻止服务启动（可能只是运维写了无关的键），
// 但必须让人看见。
func normalizeAllSectionKeys(f *ini.File) {
if f == nil {
return
}
legal := sectionKeySets()
// 1) 键名归一化（改写 ini 文件里的键名，后续 MapTo 才能读到）。
for section, keys := range legal {
sec := f.Section(section)
if sec == nil {
continue
}
renamed := normalizeSectionKeys(sec, keys)
for old, new := range renamed {
logrus.WithFields(logrus.Fields{
"section": section,
"from": old,
"to": new,
}).Info("配置键名已自动纠正（该键原本会被静默忽略）")
}
}
// 2) 未知键告警。
for _, u := range detectUnknownSections(f, legal) {
for _, key := range u.Keys {
fields := logrus.Fields{"section": u.Section, "key": key}
if s, ok := u.Suggestions[key]; ok {
fields["suggestion"] = s
logrus.WithFields(fields).Warn("配置文件中存在无法识别的键（已被忽略，该项配置不会生效）")
continue
}
logrus.WithFields(fields).Warn("配置文件中存在无法识别的键（已被忽略，该项配置不会生效）")
}
}
}
// normalizeSectionKeys 归一化一个段内的键名，并把归一化结果写回 ini 文件。
//
// 行为：
// - 遍历段内所有键，计算归一化键名；
// - 若归一化键名与原键名不同，且归一化键名在该段白名单内 → 用归一化名替换；
// - 若归一化键名是别名且白名单内 → 用正确键名替换；
// - 否则保留原样（交给未知键告警处理，不擅自猜测）。
//
// 返回被改写的键名对（原名 → 新名），供调用方记日志。
func normalizeSectionKeys(sec *ini.Section, legal map[string]bool) map[string]string {
renamed := map[string]string{}
if sec == nil {
return renamed
}
type rename struct {
old string
new string
}
var pending []rename
for _, key := range sec.Keys() {
old := key.Name()
norm := normalizeKeyName(old)
if norm == "" || norm == old {
continue
}
if !legal[norm] {
// 归一化后的名字不是本段的合法键名 —— 可能是真写错了，
// 也可能是别段的键。不要擅自猜测，交给未知键告警。
continue
}
// 目标键名已存在时保留原键（显式的正确写法优先于需要猜测的写法）。
if sec.HasKey(norm) {
continue
}
pending = append(pending, rename{old: old, new: norm})
}
for _, r := range pending {
val := sec.Key(r.old).Value()
sec.DeleteKey(r.old)
sec.NewKey(r.new, val)
renamed[r.old] = r.new
}
return renamed
}
internal/conf/keynorm_test.go
-462
View File
@@ -1,462 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package conf
import (
"path/filepath"
"strings"
"testing"
"gopkg.in/ini.v1"
)
// TestNormalizeKeyName 覆盖键名归一化的各种手写失误。
//
// 现场背景：运维写成 `honeypot_retention_days`（多一个 t）且写成
// `honeypot_retention_days <= 30`，ini 把键名解析成
// "honeypot_retention_days <"（带尾随比较符），完全匹配不上任何配置项，
// 静默失效 —— 表现为「自动清理未启用」，现场毫无线索。
func TestNormalizeKeyName(t *testing.T) {
cases := []struct {
name string
in string
want string
}{
{"正常键名不变", "honeypot_retain_days", "honeypot_retain_days"},
{"多一个 t 的误拼", "honeypot_retention_days", "honeypot_retain_days"},
{"误拼加尾随比较符", "honeypot_retention_days <", "honeypot_retain_days"},
{"尾随 <= ", "honeypot_retain_days<=", "honeypot_retain_days"},
{"首尾空白", " honeypot_retain_days ", "honeypot_retain_days"},
{"空白加比较符", " honeypot_retain_days < ", "honeypot_retain_days"},
{"多个尾随符号", "honeypot_retain_days<< ", "honeypot_retain_days"},
{"空串", "", ""},
{"纯符号", "<<<", ""},
{"大小写不归一", "HONEYPOT_RETAIN_DAYS", "HONEYPOT_RETAIN_DAYS"},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
if got := normalizeKeyName(c.in); got != c.want {
t.Errorf("normalizeKeyName(%q) = %q, want %q", c.in, got, c.want)
}
})
}
}
// TestNormalizeSectionKeys 验证段内键名改写：错拼的键被纠正到正确名字。
func TestNormalizeSectionKeys(t *testing.T) {
src := `
[security]
enable_honeypot = true
honeypot_retention_days <= 30
honeypot_auto_clean = true
`
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, []byte(src))
if err != nil {
t.Fatalf("parse ini: %v", err)
}
sec := f.Section("security")
legal := legalKeysOf(&Security)
renamed := normalizeSectionKeys(sec, legal)
if len(renamed) == 0 {
t.Fatalf("期望有键名被改写，实际没有")
}
if !sec.HasKey("honeypot_retain_days") {
t.Errorf("改写后应存在 honeypot_retain_days，实际键: %v", sec.KeyStrings())
}
// 值必须原样保留（30），不能因为改写丢值。
if got := sec.Key("honeypot_retain_days").Value(); got != "30" {
t.Errorf("改写后值 = %q, want %q", got, "30")
}
// 归一化后的键名必须真的能被 MapTo 读到 —— 这是整个修复的落点。
if err := sec.MapTo(&Security); err != nil {
t.Fatalf("map security: %v", err)
}
if Security.HoneypotRetainDays != 30 {
t.Errorf("HoneypotRetainDays = %d, want 30", Security.HoneypotRetainDays)
}
}
// TestNormalizeSectionKeysKeepsExplicit 验证正确键名存在时不会被别名的值覆盖。
//
// 显式写对的键优先级必须高于需要猜测的别名 —— 否则运维改了正确写法反而失效。
func TestNormalizeSectionKeysKeepsExplicit(t *testing.T) {
src := `
[security]
honeypot_retain_days = 7
honeypot_retention_days = 30
`
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, []byte(src))
if err != nil {
t.Fatalf("parse ini: %v", err)
}
sec := f.Section("security")
normalizeSectionKeys(sec, legalKeysOf(&Security))
if got := sec.Key("honeypot_retain_days").Value(); got != "7" {
t.Errorf("显式键应保留原值, got %q, want %q", got, "7")
}
}
// TestNormalizeSectionKeysUnknownNotGuessed 验证无法识别的键不会被「猜」成某个配置项。
//
// 归一化只能纠正「意图明确」的写法；对真正拼错的键必须保持原样，
// 交由未知键告警提示 —— 擅自猜测会让配置静默变成另一个意思，比不猜更危险。
func TestNormalizeSectionKeysUnknownNotGuessed(t *testing.T) {
src := `
[security]
totally_bogus_key = 1
`
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, []byte(src))
if err != nil {
t.Fatalf("parse ini: %v", err)
}
sec := f.Section("security")
normalizeSectionKeys(sec, legalKeysOf(&Security))
if !sec.HasKey("totally_bogus_key") {
t.Errorf("无法识别的键应保持原样，不应被改写；实际键: %v", sec.KeyStrings())
}
}
// TestDetectUnknownSections 验证未知键被检出并给出建议。
func TestDetectUnknownSections(t *testing.T) {
src := `
[security]
enable_honeypot = true
honeypot_retention_days = 30
honeypot_totally_bogus = 1
`
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, []byte(src))
if err != nil {
t.Fatalf("parse ini: %v", err)
}
unknown := detectUnknownSections(f, sectionKeySets())
var sec *unknownSection
for i := range unknown {
if unknown[i].Section == "security" {
sec = &unknown[i]
}
}
if sec == nil {
t.Fatalf("应检出 security 段的未知键，实际: %+v", unknown)
}
found := false
for _, k := range sec.Keys {
if k == "honeypot_totally_bogus" {
found = true
}
}
if !found {
t.Errorf("未知键列表应含 honeypot_totally_bogus，实际: %v", sec.Keys)
}
}
// TestDetectUnknownSectionsNoFalsePositive 验证合法键不会被误报为未知。
//
// 误报比漏报更烦人：每次启动都刷一屏 WARN，运维会麻木。
func TestDetectUnknownSectionsNoFalsePositive(t *testing.T) {
src := `
[app]
external_url = "http://127.0.0.1:8080"
production = true
[security]
enable_honeypot = true
honeypot_auto_clean = true
honeypot_max_rows = 200000
honeypot_retain_days = 30
honeypot_threshold = 1
honeypot_ban_minutes = 15
honeypot_paths = "/a,/b"
enable_auto_ban = true
ban_threshold_sensitive = 5
security_alert_email = "[email protected]"
[server]
port = 8080
salt = "s"
xsrf_key = "k"
[database]
type = "postgres"
name = "x"
schema = "public"
[limits]
max_tags = 5
`
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, []byte(src))
if err != nil {
t.Fatalf("parse ini: %v", err)
}
unknown := detectUnknownSections(f, sectionKeySets())
for _, u := range unknown {
// [service] 段是子段结构，合法键在前缀段上，不在本段。
if u.Section == "service" {
continue
}
t.Errorf("合法键被误报为未知: 段 %s 键 %v", u.Section, u.Keys)
}
}
// TestClosestKey 验证建议算法能给出有用的近似键名。
func TestClosestKey(t *testing.T) {
legal := map[string]bool{
"honeypot_retain_days": true,
"honeypot_max_rows": true,
"enable_honeypot": true,
}
if got := closestKey("honeypot_retention_days", legal); got != "honeypot_retain_days" {
t.Errorf("closestKey = %q, want %q", got, "honeypot_retain_days")
}
if got := closestKey("enable_honeypot_hit", legal); got != "enable_honeypot" {
t.Errorf("closestKey = %q, want %q", got, "enable_honeypot")
}
// 毫无关系的键不应给建议（避免噪音）。
if got := closestKey("zzzzzz", legal); got != "" {
t.Errorf("closestKey 应返回空, got %q", got)
}
}
// TestSanitizeHoneypotDefaults 验证蜜罐配置的缺省值与语义修正。
//
// 核心是三件事：
// 1. 未配置保留期 → 回退 30 天（而不是 0 = 永不清理）；
// 2. 显式 honeypot_auto_clean = false → 尊重为关闭（这是明确的关闭意图）；
// 3. 未配置自动清理 → 开启（ini 的 bool 零值是 false，若不区分就等于默认关闭）。
func TestSanitizeHoneypotDefaults(t *testing.T) {
cases := []struct {
name string
src string
wantRetain int
wantMaxRows int
wantAutoClean bool
wantThreshold int
wantBan int
}{
{
name: "全未配置时回退安全默认值",
src: "[security]\nenable_honeypot = true\n",
wantRetain: DefaultHoneypotRetainDays,
wantMaxRows: DefaultHoneypotMaxRows,
wantAutoClean: true,
wantThreshold: DefaultHoneypotThreshold,
wantBan: DefaultHoneypotBanMinutes,
},
{
name: "显式关闭自动清理被尊重",
src: "[security]\nhoneypot_auto_clean = false\n",
wantRetain: DefaultHoneypotRetainDays,
wantMaxRows: DefaultHoneypotMaxRows,
wantAutoClean: false,
wantThreshold: DefaultHoneypotThreshold,
wantBan: DefaultHoneypotBanMinutes,
},
{
name: "显式保留期被采用",
src: "[security]\nhoneypot_retain_days = 7\n",
wantRetain: 7,
wantMaxRows: DefaultHoneypotMaxRows,
wantAutoClean: true,
wantThreshold: DefaultHoneypotThreshold,
wantBan: DefaultHoneypotBanMinutes,
},
{
name: "保留期写成 0 回退默认而非永不清理",
src: "[security]\nhoneypot_retain_days = 0\n",
wantRetain: DefaultHoneypotRetainDays,
wantMaxRows: DefaultHoneypotMaxRows,
wantAutoClean: true,
wantThreshold: DefaultHoneypotThreshold,
wantBan: DefaultHoneypotBanMinutes,
},
{
name: "行数上限显式 0 表示不限",
src: "[security]\nhoneypot_max_rows = 0\n",
wantRetain: DefaultHoneypotRetainDays,
wantMaxRows: 0,
wantAutoClean: true,
wantThreshold: DefaultHoneypotThreshold,
wantBan: DefaultHoneypotBanMinutes,
},
{
name: "显式封禁时长被采用",
src: "[security]\nhoneypot_ban_minutes = 90\n",
wantRetain: DefaultHoneypotRetainDays,
wantMaxRows: DefaultHoneypotMaxRows,
wantAutoClean: true,
wantThreshold: DefaultHoneypotThreshold,
wantBan: 90,
},
{
// 0 是逃生口：留着让 autoban 回退 ban_duration_minutes，
// sanitize 不做覆盖（只告警），故期望值仍是 0。
name: "封禁时长写 0 交给 autoban 回退 ban_duration_minutes",
src: "[security]\nhoneypot_ban_minutes = 0\n",
wantRetain: DefaultHoneypotRetainDays,
wantMaxRows: DefaultHoneypotMaxRows,
wantAutoClean: true,
wantThreshold: DefaultHoneypotThreshold,
wantBan: 0,
},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, []byte(c.src))
if err != nil {
t.Fatalf("parse ini: %v", err)
}
// 重置全局，避免用例间互相污染。
Security.HoneypotRetainDays = 0
Security.HoneypotMaxRows = 0
Security.HoneypotAutoClean = false
Security.HoneypotThreshold = 0
Security.HoneypotBanMinutes = 0
File = f
if err := f.Section("security").MapTo(&Security); err != nil {
t.Fatalf("map security: %v", err)
}
sanitizeHoneypot()
if Security.HoneypotRetainDays != c.wantRetain {
t.Errorf("HoneypotRetainDays = %d, want %d", Security.HoneypotRetainDays, c.wantRetain)
}
if Security.HoneypotMaxRows != c.wantMaxRows {
t.Errorf("HoneypotMaxRows = %d, want %d", Security.HoneypotMaxRows, c.wantMaxRows)
}
if Security.HoneypotAutoClean != c.wantAutoClean {
t.Errorf("HoneypotAutoClean = %v, want %v", Security.HoneypotAutoClean, c.wantAutoClean)
}
if Security.HoneypotThreshold != c.wantThreshold {
t.Errorf("HoneypotThreshold = %d, want %d", Security.HoneypotThreshold, c.wantThreshold)
}
if Security.HoneypotBanMinutes != c.wantBan {
t.Errorf("HoneypotBanMinutes = %d, want %d", Security.HoneypotBanMinutes, c.wantBan)
}
})
}
}
// TestLegalKeysOfCoversStruct 验证合法键集合确实覆盖了结构体的所有 ini tag。
//
// 这是「未知键告警」不误报的前提：如果 legalKeysOf 漏了某个 tag，
// 每次启动都会误报该键。
func TestLegalKeysOfCoversStruct(t *testing.T) {
legal := legalKeysOf(&Security)
for _, want := range []string{
"enable_honeypot",
"honeypot_paths",
"honeypot_retain_days",
"honeypot_auto_clean",
"honeypot_max_rows",
"honeypot_threshold",
"honeypot_ban_minutes",
} {
if !legal[want] {
t.Errorf("合法键集合缺少 %q", want)
}
}
}
// TestSampleIniHasNoUnknownKeys 用官方样例配置文件做回归检测。
//
// 意义：conf/app.sample.ini 是运维照抄的模板，它里面的每个键都必须能被代码识别。
// 一旦结构体改了字段名而 sample.ini 没同步（或反之），这个测试就会失败 ——
// 而不是等到某次部署时启动日志里飘出一堆「无法识别的键」让人摸不着头脑。
//
// 同时也保证未知键检测不会对官方模板误报。
func TestSampleIniHasNoUnknownKeys(t *testing.T) {
path := filepath.Join("..", "..", "conf", "app.sample.ini")
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, path)
if err != nil {
t.Skipf("跳过：无法读取样例配置 %s（%v）", path, err)
}
unknown := detectUnknownSections(f, sectionKeySets())
for _, u := range unknown {
// [service] 是子段结构（每个后端一个子段），键在子段上，不在本段。
if u.Section == "service" {
continue
}
for _, k := range u.Keys {
t.Errorf("样例配置中存在无法识别的键: 段 %s 键 %q", u.Section, k)
}
}
}
// TestSampleIniValuesHaveNoInlineComment 守住「行尾注释会被并入值」的陷阱。
//
// conf.Init 用 ini.LoadOptions{IgnoreInlineComment: true}，该选项的语义是
// **不剥离**行尾注释（实测 `port = 1440 ; 注释` → 值 "1440 ; 注释"，
// int 解析失败，而 MapTo 仍然返回 nil error）。后果是该配置项静默回退零值，
// 日志里只会说「配置值不对」，根本联想不到是注释造成的。
//
// 样例配置曾经全线是 `key = value ; 注释` 的写法：text_censor_source 因此
// 让 conf.Init 直接拒绝启动，ip_blacklist / security_alert_email 变成带注释的
// 垃圾字符串，honeypot_max_rows / honeypot_auto_clean 静默失效。
//
// 直接检查每个键的值里没有 ';'，比逐个字段断言更彻底，也不会漏掉新加的配置项。
func TestSampleIniValuesHaveNoInlineComment(t *testing.T) {
path := filepath.Join("..", "..", "conf", "app.sample.ini")
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, path)
if err != nil {
t.Skipf("跳过：无法读取样例配置 %s（%v）", path, err)
}
for _, sec := range f.Sections() {
for _, k := range sec.Keys() {
if strings.Contains(k.Value(), ";") {
t.Errorf("样例配置 [%s] %s 的值含 ';'：%q —— 行尾注释会被并入值，该项将静默失效",
sec.Name(), k.Name(), k.Value())
}
}
}
}
// TestNormalizeAllSectionKeysEndToEnd 走完整链路：
// 加载带错拼键的配置 → 归一化 → MapTo → 拿到正确的保留期。
//
// 这正是现场故障的完整复现路径。
func TestNormalizeAllSectionKeysEndToEnd(t *testing.T) {
src := `
[security]
enable_honeypot = true
honeypot_auto_clean = true
honeypot_max_rows = 200000
honeypot_retention_days <= 30
`
f, err := ini.LoadSources(ini.LoadOptions{IgnoreInlineComment: true}, []byte(src))
if err != nil {
t.Fatalf("parse ini: %v", err)
}
File = f
Security.HoneypotRetainDays = 0
Security.HoneypotAutoClean = false
Security.HoneypotMaxRows = 0
Security.HoneypotThreshold = 0
normalizeAllSectionKeys(f)
if err := f.Section("security").MapTo(&Security); err != nil {
t.Fatalf("map security: %v", err)
}
sanitizeHoneypot()
if Security.HoneypotRetainDays != 30 {
t.Errorf("HoneypotRetainDays = %d, want 30（错拼键应被纠正并生效）", Security.HoneypotRetainDays)
}
if !Security.HoneypotAutoClean {
t.Errorf("HoneypotAutoClean = false, want true")
}
if Security.HoneypotMaxRows != 200000 {
t.Errorf("HoneypotMaxRows = %d, want 200000", Security.HoneypotMaxRows)
}
// 归一化后不应再残留「带比较符」的怪键名。
for _, k := range f.Section("security").KeyStrings() {
if strings.ContainsAny(k, "<>") {
t.Errorf("残留带比较符的键名: %q", k)
}
}
}
internal/conf/limits.go
+45 -21
View File
@@ -23,39 +23,62 @@ const (
// LimitsConfig 全站内容 / 数量上限（[limits] 配置段）的字段集合。
//
// 收口到本段前，这些上限散落在 internal/db 与路由层硬编码，改一次要重编译且前后端数值易漂移。
// 现后端校验 / 模板注入 / 前端提示统一引用同一份值，调整只需改 app.ini 重启；
// 长度类上限一律按字符（rune）计数。
// 过去这些上限以常量形式散落在 internal/db（MaxTags / MaxCustomTextLen 等）与
// 路由层硬编码（私聊单条 2000 字、会话条数 clamp 5~200 等）中，调整需改代码重编译，
// 且前后端、i18n 文案各自携带一份数值容易漂移。统一收口到 [limits] 段后：
// - 后端校验、模板注入、前端提示全部引用 conf.Limits 的同一份值；
// - 调整仅需修改 conf/app.ini 并重启进程，无需改代码；
// - 长度类上限统一按字符（rune / Unicode 码点）计数。
type LimitsConfig struct {
MaxTags int `ini:"max_tags"`
MaxTagLen int `ini:"max_tag_len"`
MaxBlockWords int `ini:"max_block_words"`
// ── 标签与屏蔽词（账号设置页）──
// 标签个数上限
MaxTags int `ini:"max_tags"`
// 单个标签最大字符数
MaxTagLen int `ini:"max_tag_len"`
// 屏蔽词个数上限
MaxBlockWords int `ini:"max_block_words"`
// 单个屏蔽词最大字符数
MaxBlockWordLen int `ini:"max_block_word_len"`
// 参与者填写的「自定义补充选项」文本最大字符数（含表单字段的「其他」）。
// ── 投票 ──
// 参与者填写的「自定义补充选项」文本最大字符数。
// 覆盖两类入口：单选/多选/排序的全局补充选项，以及表单收集字段的
// 「其他/自定义选项」（field_{id}_custom）。
CustomAnswerLen int `ini:"custom_answer_len"`
// 站长创建投票时单个「选项」文本最大字符数。与 CustomAnswerLen 是两条独立规则
// （站长侧预设刻意放宽），可各自调参。
// 站长创建投票时单个「选项」文本的最大字符数。
// 覆盖单选/多选/排序的预设选项，以及表单收集字段（select/radio/checkbox/rank）
// 的预置选项。与 CustomAnswerLen 是两条独立规则（站长侧预设刻意放宽），可各自调参。
VoteOptionLen int `ini:"vote_option_len"`
// 提问正文最大字符数。旧实现靠 govalid maxlen 写死 2000 且与前端 1000 不一致，
// 现改为路由层按本值做 rune 校验。
// ── 提问 / 回答 / 追问 ──
// 提问正文最大字符数（访客向提问箱提交的问题内容）。
// 旧实现依赖 govalid 的 maxlen 标签（编译期写死 2000），无法随配置调整，
// 且与前端 maxlength=1000 不一致，现已移到路由层按本值做 rune 校验。
QuestionContentLen int `ini:"question_content_len"`
// 回答正文最大字符数：箱主对提问的正式回答，以及对追问的回复（共用）。
AnswerContentLen int `ini:"answer_content_len"`
// 回答正文最大字符数：箱主对提问的正式回答，以及箱主对追问的回复（共用）。
AnswerContentLen int `ini:"answer_content_len"`
// 追问正文最大字符数（提问者在问题被回答后继续追问的内容）。
FollowUpContentLen int `ini:"followup_content_len"`
// ── 私聊 ──
// 单条消息（发送 / 回复共用）最大字符数
ChatMessageLen int `ini:"chat_message_len"`
// 每个会话的消息条数硬顶。用户只能在 1..该值间设置 chat_max_messages，
// 新用户默认值即该硬顶（而非固定 20）。
// 每个私聊会话的消息条数上限（系统硬顶）。用户只能在 1..该值 之间设置自己的
// chat_max_messages；新注册用户的默认值即该硬顶（而非固定 20）。
ChatMaxMessages int `ini:"chat_max_messages"`
// 每日私信条数的「用户可设上限」（非站点强制配额）：用户可设 0..该值，0 表示不限制。
// 单用户每日私信条数上限（用户可设范围 0..该值；0 表示不限制每日条数）。
// 该值只是「用户可设置的上限」，不是站点强制的每日配额。
DailyMessageLimitMax int `ini:"daily_message_limit_max"`
}
// Limits 保存运行时的全部上限配置。conf.Init 先 MapTo [limits] 段，再由 sanitizeLimits
// 把 <1 的值回退内置默认，因此缺段、缺键、留空（解析为 0）或填负数都不会让上限静默置零。
// Limits 保存运行时的全部上限配置。conf.Init 中会先 MapTo [limits] 段覆盖显式键，
// 再调用 sanitizeLimits 把 <1 的值回退到内置默认，因此：
// - 缺失 [limits] 段或个别键 → 使用内置默认；
// - ini 键留空（int 解析为 0）或误填 0/负数 → 自动回退默认，不会把上限静默置零。
var Limits = LimitsConfig{
MaxTags: defaultMaxTags,
MaxTagLen: defaultMaxTagLen,
@@ -71,9 +94,10 @@ var Limits = LimitsConfig{
DailyMessageLimitMax: defaultDailyMessageLimitMax,
}
// sanitizeLimits 归一化 [limits]：所有上限最小为 1，0 / 负数一律回退内置默认，
// 避免「留空=0」把标签全拒、消息全超长等隐性灾难。
// DailyMessageLimitMax 同样要求 >=1：为 0 会让用户只能设为 0（=不限制），等于关闭每日配额功能。
// sanitizeLimits 归一化 [limits] 配置：所有上限最小为 1（0 / 负数说明未配置或手滑，
// 一律回退内置默认，避免「留空=0」把标签全拒、消息全超长等隐性灾难）。
// 注意 DailyMessageLimitMax 同样要求 >=1：0 会让用户侧永远只能设为 0（=不限制），
// 语义上等于关闭每日配额功能，需显式使用该字段其余语义时请另行设计。
func sanitizeLimits(l *LimitsConfig) {
clamp1 := func(p *int, def int) {
if *p < 1 {
internal/conf/static.go
+33 -179
View File
@@ -4,21 +4,12 @@
package conf
// ⚠️ 仅应由 "-ldflags" 注入。
// Build time and commit information.
//
// ⚠️ WARNING: should only be set by "-ldflags".
var (
BuildTime string
BuildCommit = "dev"
// StaticVersion 静态资源缓存版本号：base.css 与主题 css 共用，改样式只改这一处。
StaticVersion = "20261022c"
)
// 文本审核通道取值（[security] text_censor_source）。定义在 conf 侧，
// 让配置校验（conf.Init）与通道装配（internal/security/censor）共用同一份字面量。
const (
CensorSourceAuto = "auto" // 七牛优先、阿里云兜底（历史行为，留空同义）
CensorSourceQiniu = "qiniu"
CensorSourceAliyun = "aliyun"
)
var (
@@ -38,162 +29,34 @@ var (
FontPath string `ini:"font_path"`
}
// Theme 主题系统（[theme] 段）。
// default ：站点默认主题 slug，留空/非法回退内置 default（= 现在的外观）。
// available ：启用哪些主题（逗号分隔），同时是箱主设置页的白名单；
// 列了但缺少 css 文件的会被忽略并告警（见 internal/theme）。
Theme struct {
Default string `ini:"default"`
Available string `ini:"available"`
}
// Announcement 站内公告（[announcement] 段）。解析与展示判定见 announcement.go。
Announcement announcementConfig
Security struct {
EnableTextCensor bool `ini:"enable_text_censor"`
IPBlacklist string `ini:"ip_blacklist"`
IPBlacklistRedirectURL string `ini:"ip_blacklist_redirect_url"`
// TrustProxy 为 true 时信任 CDN 权威客户端头 CF-Connecting-IP / EO-Client-IP
// （以及受信代理设置的 X-Real-IP / X-Forwarded-For）；否则一律用 RemoteAddr，
// 防止伪造 header 绕过速率限制与 IP 黑名单。
// ⚠️ 权威头只在 TCP 对端可信（回环，或命中 TrustedProxies）时才会被采信 ——
// 见 shared.ResolveClientIP：公网对端带来的权威头一律忽略（P1-3 修复）。
// （以及受信代理设置的 X-Real-IP / X-Forwarded-For）；否则一律使用 RemoteAddr，
// 防止客户端伪造 header 绕过速率限制与 IP 黑名单。
TrustProxy bool `ini:"trust_proxy"`
// TrustedProxies 逗号分隔的 IP / CIDR，仅限自己的反向代理 / LB。仅当 TCP 对端
// 落在该清单内才解析 X-Forwarded-For / X-Real-IP；留空则这两个头永不被信任。
// 回环地址（127.0.0.1 / ::1）无需登记即视为可信对端：cloudflared / 本机 nginx
// 回源的连接必然由本机进程发起，外部无法伪造。
// CDN 直连回源（非 Tunnel）的部署形态下，必须把该 CDN 的回源网段登记到这里，
// 否则它的权威头会被忽略、客户端 IP 退化为 CDN 边缘 IP。
// TrustedProxies 逗号分隔的 IP / CIDR 列表，仅限“你自己的”反向代理/负载均衡基础设施
// （例如本机 nginx 的 127.0.0.1、私有网络 LB）。仅当 TCP 对端落在该清单内时才会解析
// X-Forwarded-For / X-Real-IP。留空则这两个头永不被信任（CDN 权威头 CF-Connecting-IP /
// EO-Client-IP 仍会被采用，前提是源站已被对应 CDN 锁定）。
// 目的：避免维护 Cloudflare / EdgeOne 等上游 CDN 的庞大 CIDR 清单——源站应配合
// Cloudflare Tunnel / Authenticated Origin Pull / 防火墙仅放行 CDN 回源网段锁定，
// 使 CF-Connecting-IP / EO-Client-IP 成为权威客户端 IP。
TrustedProxies string `ini:"trusted_proxies"`
EnableAutoBan bool `ini:"enable_auto_ban"` // fail2ban 风格：检测到扫描特征后临时封禁来源 IP
// BanTrackNotFound 是否把未注册路径的 404 计入封禁统计。默认 false：仅命中后台
// 扫描特征路径（KindSensitive）才统计，避免共享出口（CDN 边缘 / CGNAT）下
// 正常用户被 404 探测流量连坐误伤。
BanTrackNotFound bool `ini:"ban_track_notfound"`
BanThresholdSensitive int `ini:"ban_threshold_sensitive"` // 窗口内敏感路径命中次数
BanThreshold404 int `ini:"ban_threshold_404"` // 窗口内 404 次数
BanWindowSeconds int `ini:"ban_window_seconds"` // 统计窗口（秒）
BanDurationMinutes int `ini:"ban_duration_minutes"` // 封禁时长（分钟）
// DefaultModerationStrictness 站点默认审核严格度（lax / standard / strict），
// 仅对未单独设置档位的账号生效（见 moderation.StrictnessFor）。留空或非法值回退
// strict（最严档），保证升级不会放宽拦截；默认拦截面可能较升级前略有扩大，
// 希望更少误伤则显式写 standard。
DefaultModerationStrictness string `ini:"default_moderation_strictness"`
// TextCensorSource 文本审核通道：qiniu / aliyun（内容安全 2.0 TextModeration，
// 个人实名账号即可开通）/ auto（默认，留空同义：七牛优先、阿里云复核）。
// 仅显式选定的通道会被调用，缺凭据时启动即报错（见 conf.Init）——
// 审核失败是 fail-closed（拒绝提交），会让发布与私信整站不可用且现象隐蔽。
TextCensorSource string `ini:"text_censor_source"`
// EnableHoneypot 开启「虚假后台登录界面」蜜罐：扫描器探测后台路径时
// 返回一个仿 WordPress 的假登录页，并记录其提交的用户名/密码等破解信息。
// 仅在「无任何路由匹配」的路径上生效，与真实业务路由零交集。
EnableHoneypot bool `ini:"enable_honeypot"`
// HoneypotPaths 追加自定义诱饵路径（逗号分隔），与内置清单并集。
HoneypotPaths string `ini:"honeypot_paths"`
// HoneypotRetainDays 蜜罐命中记录的保留天数，到期自动清理。
// ⚠️ 键名是 honeypot_retain_days（没有 tion）。写成 honeypot_retention_days
// 会被 ini 静默忽略 —— 现场踩过这个坑，表现为「自动清理未启用」。
// 缺省 30 天（见 sanitizeHoneypot）；显式 <= 0 也回退 30。
// 要关闭自动清理请用 honeypot_auto_clean = false。
HoneypotRetainDays int `ini:"honeypot_retain_days"`
// HoneypotAutoClean 是否启用蜜罐记录的后台自动保留期清理。
// 缺省 true：honeypot_hits 是只追加的审计表，写入完全由外部扫描流量驱动，
// 没有自动清理的话表体积只增不减（这是「数据库被扫描撑爆」的真实路径）。
// 关闭后仍可手动执行 TamaBox honeypot prune。
// ⚠️ 缺省值靠 HasKey 判定（见 sanitizeHoneypot）：ini 的 bool 解析是
// 「有键才赋值」，若只看零值就无法区分「未配置」与「显式关闭」。
HoneypotAutoClean bool `ini:"honeypot_auto_clean"`
// HoneypotMaxRows 蜜罐命中记录的行数上限。缺省 200000（约 53 MB）。
// 显式写 0 表示不设上限（逃生口，会告警提醒表只增不减）。
// 保留期是时间维度的上界，但攻击者可以用海量源 IP 在保留期内把表撑爆，
// 这是第二道闸。实测单行约 281 字节（含索引，常规 UA），20 万行约 53 MB。
HoneypotMaxRows int `ini:"honeypot_max_rows"`
// HoneypotThreshold 蜜罐「提交凭据」多少次即封禁。默认 1（一次即封）：
// 往假后台里填账号密码是证据最强的行为，抓到一次就足够。
// ⚠️ 它不作用于纯路径探测（GET 看一眼假登录页）—— 那类请求走常规
// ban_threshold_sensitive，否则扫描器 GET 一次就被封，永远走不到
// POST 提交凭据那一步，蜜罐也就拿不到字典。
// 缺省回退 1（见 sanitizeHoneypot）。
HoneypotThreshold int `ini:"honeypot_threshold"`
// HoneypotBanMinutes 蜜罐封禁时长（分钟）。缺省 1440（24 小时），
// 刻意远长于 ban_duration_minutes：命中蜜罐意味着对方已在提交账号密码，
// 证据强度高于单纯路径探测（见 DefaultHoneypotBanMinutes）。
// 显式 <= 0 表示回退 ban_duration_minutes。
HoneypotBanMinutes int `ini:"honeypot_ban_minutes"`
// HoneypotCredDir 凭据取证文件的存放目录。
//
// ⚠️ 捕获到的用户名/密码**不入库**，只追加到这个目录下的按天文件
// （creds-YYYY-MM-DD.jsonl，一行一条 JSON）。原因：明文账号密码一旦入库，
// 就会跟着进备份、主从复制和任何能连库的报表工具，事后无法彻底清除。
// 目录会被强制为 0700、文件 0600；留空使用默认 data/honeypot-creds。
// 目录不可写时只降级为「不保存凭据」，不会影响站点启动。
HoneypotCredDir string `ini:"honeypot_cred_dir"`
// BanImagePath 被封禁时返回的图片路径（本地文件，相对路径以进程工作目录为基准）。
//
// 留空、文件读不到、或内容不是图片时，一律回退为纯文字 "403 Forbidden" ——
// 这条路径绝不能因为一张图把「拒绝」响应弄坏，更不能让缺失的资源变成 500。
//
// 只接受 image/* 的内容：如果配成 app.ini 之类的文件会被拒绝并告警，
// 否则等于把配置文件当响应体吐给每一个被封的攻击者。
BanImagePath string `ini:"ban_image_path"`
SecurityAlertEmail string `ini:"security_alert_email"` // 触发封禁时告警收件人（留空不发送）
// ⚠️ security_alert_email 也是蜜罐告警邮件的收件人，而蜜罐邮件正文
// **含明文账号密码**（这是功能核心价值：运维立刻拿到攻击者正在用的字典）。
// 因此这里必须是**个人邮箱**，禁止填群组邮箱 / 分发列表 / 团队共用邮箱——
// 否则等于把攻击者的破解字典广播给无关人员，且经 SMTP 中转后明文密码
// 会留在第三方邮件系统的日志/归档里，超出本地 0600 取证文件的控制范围。
// CSP 内容安全策略的生效模式：enforce / report / off，缺省 enforce。
//
// enforce 下发 Content-Security-Policy（真正拦截）；report 只下发 Report-Only
// （照常加载、只记违规），用于临时观察。默认拦截而不是观察，原因是：
// 没人会盯着 console，且不给 csp_report_uri 时 Report-Only 等于什么都没做，
// 留个不生效的开关反而制造「已防护」的错觉。默认值的安全前提是白名单已经
// 用真浏览器逐页巡检过（csp_sweep.py：20 个页面零违规）。
// 上线后发现误伤，把 csp 改成 report 或 off 再重启即可恢复，不用改代码。
CSP string `ini:"csp"`
// CSPReportURI 违规上报地址（可选）。留空时浏览器只把违规打到 console 不上报；
// 用 report 模式观察时应当配上，否则「观察一周」就只是空谈。
CSPReportURI string `ini:"csp_report_uri"`
// IPGeoProvider 蜜罐/扫描来源 IP 的地理定位数据源。
//
// ⚠️ 与 ipinfo.Lookup（cdncheck 离线指纹）是两件事：那套只认云厂商/CDN/WAF
// 的 ASN，肉鸡（家宽、企业宽带、移动网络）一律显示「未识别（普通网络）」。
// 这里回答的是「这个 IP 在哪儿」，靠的是外部 IP 库。
//
// auto（缺省）：ip-api.com 批量打底（全球覆盖、无需 key、一次 100 个），
// 配了 ip_geo_tencent_key 时再用腾讯位置服务精修国内 IP
// （省市 + GCJ-02 坐标）。腾讯的 IP 定位是一 IP 一请求，
// 拿它做批量主干会把 N 个 IP 变成 N 次 HTTP，故只做精修。
// ipapi：只用 ip-api.com
// tencent：只用腾讯位置服务（要求配 key，否则降级为 ipapi）
// none：不查询，报告里只给 IP 不提地理信息（攻击者 IP 一个字节都不外发）
//
// 隐私边界：auto/ipapi 会把攻击者 IP 发给 ip-api.com，tencent 会发给腾讯。
// 本报告只处理「攻击者」地址，不涉及任何用户 IP；不接受这一点请用 none。
IPGeoProvider string `ini:"ip_geo_provider"`
// IPGeoTencentKey 腾讯位置服务 key（lbs.qq.com 申请）。留空则跳过腾讯精修。
// 仅用于服务端 HTTP 请求，不下发到前端 —— 与地图 JS 用的 key 不是一回事。
IPGeoTencentKey string `ini:"ip_geo_tencent_key"`
// HoneypotReportEnabled 是否启用周期性安全状况汇总（周报 / 月报）邮件。
// 缺省 true：报告本身是运维最需要的「有没有人在打、从哪儿打」，
// 而收件人缺失时会 WARN 跳过，不会静默。
HoneypotReportEnabled bool `ini:"honeypot_report_enabled"`
// HoneypotReportWeekly / Monthly 分别控制周报与月报，缺省都开。
HoneypotReportWeekly bool `ini:"honeypot_report_weekly"`
HoneypotReportMonthly bool `ini:"honeypot_report_monthly"`
// HoneypotReportEmail 报告收件人。留空回退 security_alert_email。
// 单独开一个键是为了能把「随时可能发生的封禁告警」与「定期汇总」
// 分投到不同邮箱（例如告警进手机推送邮箱、汇总进归档邮箱）。
HoneypotReportEmail string `ini:"honeypot_report_email"`
// HoneypotReportDir 报告文件（HTML + PNG）的存放目录，缺省 data/reports。
// 报告里有攻击者 IP 明细，目录权限按 0700 创建。
HoneypotReportDir string `ini:"honeypot_report_dir"`
// 自动封禁（fail2ban 风格）：检测批量扫描/探测特征后临时封禁来源 IP。
EnableAutoBan bool `ini:"enable_auto_ban"`
// BanTrackNotFound 是否把「未注册路径的 404」计入封禁统计。默认 false：正常业务
// （域名/题目不存在等均走 302 业务跳转，不产生计数）一律放行，仅命中后台扫描特征
// 路径（KindSensitive）才参与统计封禁。避免共享出口（CDN 边缘 / CGNAT NAT444）下
// 正常用户被 404 探测流量连坐误伤。如需恢复对纯 404 字典扫描的封禁再置 true。
BanTrackNotFound bool `ini:"ban_track_notfound"`
BanThresholdSensitive int `ini:"ban_threshold_sensitive"` // 窗口内敏感路径命中次数
BanThreshold404 int `ini:"ban_threshold_404"` // 窗口内 404 次数
BanWindowSeconds int `ini:"ban_window_seconds"` // 统计窗口（秒）
BanDurationMinutes int `ini:"ban_duration_minutes"` // 封禁时长（分钟）
SecurityAlertEmail string `ini:"security_alert_email"` // 触发封禁时告警收件人（留空不发送）
}
Server struct {
@@ -250,23 +113,12 @@ var (
}
Mail struct {
Account string `ini:"account"`
Password string `ini:"password"`
Port int `ini:"port"`
SMTP string `ini:"smtp"`
SkipTLSVerify bool `ini:"skip_tls_verify"` // 仅自签名 / 内网 SMTP 需要
}
// Notify 站级通知通道配置（[notify] 段）。与 [mail] 的「邮件给具体收件人」不同，
// 这两个是「广播式」通道：
// - WebhookURL：通用 Webhook（Discord / Slack / 企业微信群机器人等），站级事件
// （新提问 / 新回答 / 新追问 / 新私聊 / 新投票 / 安全告警 / 举报）统一推送。
// - TelegramBotToken：Telegram Bot token，配合每个箱主自填的 chat_id 实现
// 「新提问」点对点通知。
// 两者都可留空：留空的通道对应发送静默跳过（不影响邮件等其他通道）。
Notify struct {
WebhookURL string `ini:"webhook_url"`
TelegramBotToken string `ini:"telegram_bot_token"`
Account string `ini:"account"`
Password string `ini:"password"`
Port int `ini:"port"`
SMTP string `ini:"smtp"`
// SkipTLSVerify 跳过 SMTP TLS 证书校验（仅自签名/内网 SMTP 需要，默认 false 校验证书）
SkipTLSVerify bool `ini:"skip_tls_verify"`
}
Service struct {
@@ -274,6 +126,8 @@ var (
Prefix string `ini:"prefix"`
ForwardURL string `ini:"forward_url"`
}
TLSInsecureSkipVerify bool `ini:"tls_insecure_skip_verify"` // 仅内网自签名后端需要
// TLSInsecureSkipVerify 跳过反向代理到后端服务的 TLS 证书校验
// （仅内网后端使用自签名证书时需要，默认 false 校验证书）
TLSInsecureSkipVerify bool `ini:"tls_insecure_skip_verify"`
}
)
internal/conf/text_censor_source_test.go
-55
View File
@@ -1,55 +0,0 @@
// Copyright 2022 E99p1ant. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package conf
import (
"testing"
"github.com/stretchr/testify/assert"
)
// TestValidateTextCensorSource 覆盖 [security] text_censor_source 与 [app] 凭据的搭配校验。
//
// 关注两类真实故障：
// 1. 显式选定通道却缺凭据 —— 运行期审核必然失败，而审核失败是 fail-closed，
// 会让整站发布/私信不可用且现象隐蔽，必须在启动阶段拦住；
// 2. 取值拼写错误 —— 若被静默回退成 auto，运维会误以为「已经只用七牛了」。
func TestValidateTextCensorSource(t *testing.T) {
for _, tc := range []struct {
name string
enabled bool
source string
qk, qs string
ak, as string
wantErr bool
}{
{name: "审核关闭：不校验任何通道配置", enabled: false, source: "aliyun"},
{name: "审核关闭：非法取值也不报错", enabled: false, source: "qinui"},
{name: "留空：通过（历史默认行为）", enabled: true, source: ""},
{name: "auto：通过", enabled: true, source: "auto"},
{name: "auto：无任何凭据也通过（不阻断开箱启动）", enabled: true, source: "auto"},
{name: "qiniu：凭据齐备通过", enabled: true, source: "qiniu", qk: "k", qs: "s"},
{name: "qiniu：缺 access key 报错", enabled: true, source: "qiniu", qs: "s", wantErr: true},
{name: "qiniu：缺 access secret 报错", enabled: true, source: "qiniu", qk: "k", wantErr: true},
{name: "aliyun：凭据齐备通过", enabled: true, source: "aliyun", ak: "k", as: "s"},
{name: "aliyun：缺凭据报错", enabled: true, source: "aliyun", wantErr: true},
{name: "大小写与空白不敏感", enabled: true, source: " QINIU ", qk: "k", qs: "s"},
{name: "非法取值：报错而非静默回退为 auto", enabled: true, source: "qinui", qk: "k", qs: "s", wantErr: true},
} {
t.Run(tc.name, func(t *testing.T) {
err := validateTextCensorSource(tc.enabled, tc.source, tc.qk, tc.qs, tc.ak, tc.as)
if tc.wantErr {
assert.Error(t, err)
return
}
assert.NoError(t, err)
})
}
}
internal/conf/unknown.go
-124
View File
@@ -1,124 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package conf
import (
"sort"
"strings"
"gopkg.in/ini.v1"
)
// 未知配置键检测：把「配了但不生效」的键在启动时喊出来。
//
// 为什么必须做：ini 库对未知键是静默忽略的。运维写错一个字母，
// 程序照常启动、照常服务，但那个配置完全没生效 —— 现场没有任何线索。
// 蜜罐保留期就踩过这个坑：写成 honeypot_retention_days（多一个 t），
// 代码读 honeypot_retain_days，表现为「自动清理未启用」，
// 而日志里没有任何「你的键名不认识」的提示。
//
// 检测方式：把 ini 文件里每一段的键名，与代码中该段结构体的 ini tag
// 逐一比对（合法键名由 legalKeysOf 从反射中得出，是单一事实来源）。
// 报不出来的风险点：
// - 无 ini tag 的字段（ini 用字段名做键名）→ 保守起见不登记，
// 会漏报但不会误报；
// - 段名本身写错 → 整段被忽略，这由「未知段」检测覆盖（见 unknownSections）。
// unknownSection 描述一个无法识别的配置段或键。
type unknownSection struct {
// Section 段名。
Section string
// Keys 该段内无法识别的键名（已排序）。
Keys []string
// Suggestions 键名 → 最接近的合法键名建议。
Suggestions map[string]string
}
// detectUnknownSections 检测配置文件中无法识别的段与键。
//
// 合法段名与合法键名均由调用方通过反射传入（单一事实来源）。
func detectUnknownSections(f *ini.File, knownSections map[string]map[string]bool) []unknownSection {
var out []unknownSection
if f == nil {
return out
}
for _, sec := range f.Sections() {
name := sec.Name()
legal, known := knownSections[name]
if !known {
// 未登记的段：可能是拼错，也可能是本项目不关心的段。
// 只在段内确实有键时才提示（空段无所谓）。
keys := sec.KeyStrings()
if len(keys) == 0 {
continue
}
sort.Strings(keys)
out = append(out, unknownSection{Section: name, Keys: keys})
continue
}
var bad []string
suggestions := map[string]string{}
for _, key := range sec.KeyStrings() {
if legal[key] {
continue
}
bad = append(bad, key)
if s := closestKey(key, legal); s != "" {
suggestions[key] = s
}
}
if len(bad) == 0 {
continue
}
sort.Strings(bad)
out = append(out, unknownSection{Section: name, Keys: bad, Suggestions: suggestions})
}
return out
}
// closestKey 在合法键名中找出与 unknown 最接近的一个。
//
// 用「公共前缀长度 + 包含关系」这种无需导入编辑距离算法的启发式：
// 配置键名通常是同族词（honeypot_xxx），拼错时往往仍共享较长前缀，
// 或者其中一个是另一个的子串（retain_days vs retention_days）。
func closestKey(unknown string, legal map[string]bool) string {
best := ""
bestScore := 0
for name := range legal {
score := 0
if strings.Contains(unknown, name) || strings.Contains(name, unknown) {
// 包含关系：得分按较短者的长度算，取一半折扣。
short := len(name)
if len(unknown) < short {
short = len(unknown)
}
score = short / 2
} else {
score = commonPrefixLen(unknown, name)
}
if score > bestScore {
bestScore = score
best = name
}
}
// 至少要有 6 个字符的公共部分才给建议，否则噪音大于价值。
if bestScore < 6 {
return ""
}
return best
}
// commonPrefixLen 返回两个字符串的公共前缀长度。
func commonPrefixLen(a, b string) int {
n := len(a)
if len(b) < n {
n = len(b)
}
i := 0
for i < n && a[i] == b[i] {
i++
}
return i
}
internal/context/context.go
+1 -88
View File
@@ -26,7 +26,6 @@ import (
"github.com/tamakyi/TamaBox/internal/i18n"
"github.com/tamakyi/TamaBox/internal/shared"
templatepkg "github.com/tamakyi/TamaBox/internal/template"
"github.com/tamakyi/TamaBox/internal/theme"
)
type EndpointType string
@@ -66,10 +65,7 @@ func (c *Context) HasError() bool {
if !ok {
return false
}
// 带 ok 的断言：Data 是 map[string]interface{}，任何写入方都可能塞进非 bool 值，
// 裸断言遇到那种情况会直接 panic 掉整个请求。非 bool 一律视为「无错误」。
v, isBool := hasErr.(bool)
return isBool && v
return hasErr.(bool)
}
func (c *Context) SetError(err error, f ...interface{}) {
@@ -138,11 +134,6 @@ func (c *Context) Refresh() {
}
func (c *Context) JSON(data interface{}) error {
// 显式声明内容类型：之前靠 Go 的 sniff 兜底，实测返回的是 text/plain。
// 有 nosniff 所以不会被当 HTML 渲染，但按 Content-Type 分派的客户端
// （fetch 的 .json()、axios、部分 SDK）会因此走错分支。
c.ResponseWriter().Header().Set("Content-Type", "application/json; charset=utf-8")
resp := map[string]interface{}{
"code": 0,
"data": data,
@@ -157,9 +148,6 @@ func (c *Context) ServerError() error {
}
func (c *Context) JSONError(errorCode int, message string) error {
// 必须在 WriteHeader 之前设置：一旦写出状态码，头就锁定了。
c.ResponseWriter().Header().Set("Content-Type", "application/json; charset=utf-8")
span := trace.SpanFromContext(c.Request().Context())
resp := map[string]interface{}{
@@ -251,19 +239,6 @@ func Contexter() flamego.Handler {
isUserPage := strings.HasPrefix(path, "/user") || strings.HasPrefix(path, "/_/")
c.Data["IsUserPage"] = isUserPage
// 页面作用域：让同一套主题能在不同页面摆不同装饰（箱主页/问题页/设置页…）。
// 模板通过 <html data-page-scope> 输出，主题 css 用
// html[data-theme-style="x"][data-page-scope="y"] 覆盖 --tb-deco 等令牌。
// 未知路径为空串，此时只应用全局装饰，行为与引入该机制前完全一致。
c.Data["PageScope"] = pageScope(path)
// 主题：/user 后台是箱主本人的页面，跟随本人配置；
// /_/{domain} 的箱主主题由 question.Pager 覆盖（访客看到的是箱主的选择）。
// 空串（未选且站点无默认主题）= 不加载主题 css。
if isThemeScope(path) && c.IsLogged {
c.Data["ThemeSlug"] = theme.Resolve(c.User.Theme)
}
// SEO：仅公开页（首页/注册/登录/explore）允许被搜索引擎收录；
// 提问内容（提问箱页、单题页）、密码页、私信、用户后台等隐私页一律 noindex。
isPublicPage := path == "/" || path == "/register" || path == "/login" || strings.HasPrefix(path, "/explore")
@@ -309,8 +284,6 @@ func Contexter() flamego.Handler {
c.Data["CurrentURI"] = ctx.Request().Request.RequestURI
c.Data["ExternalURL"] = conf.App.ExternalURL
// 静态资源版本号：base.css 与主题 css 共用同一个值，改样式只需改 conf.StaticVersion。
c.Data["StaticVersion"] = conf.StaticVersion
// 默认头像/背景图兜底：未设置自定义头像的箱主，其二维码 logo 应与页面头像一致回退到 default_avatar。
// 模板按原始 URL 直连（easy.qrcode 以 crossOrigin:'anonymous' 加载，配合对象存储桶 CORS
@@ -352,63 +325,3 @@ func (c *Context) Lang() string {
}
return i18n.Default
}
// isThemeScope 判断该路径的主题是否由「当前登录用户自己的配置」决定。
// 只覆盖 /user 后台（本人页面）；提问箱相关页面由 question.Pager 按箱主注入，
// 公开页（首页/探索/登录）保持站点默认外观，不跟随登录状态变化。
func isThemeScope(path string) bool {
return path == "/user" || strings.HasPrefix(path, "/user/")
}
// pageScope 把请求路径归类成「主题页面作用域」。
//
// 目的：同一个主题在不同页面可以摆不同装饰（箱主页放人物、问题页只留光、设置页干脆不放图），
// 而不必为每种页面复制一整套主题。模板把它输出到 <html data-page-scope="...">，
// 主题 css 用 html[data-theme-style="x"][data-page-scope="y"] 覆盖 --tb-deco 等令牌。
//
// 返回空串表示「不在主题作用域内」（首页/探索/登录等公开页也可返回具体值，
// 只是这些页面通常不带 ThemeSlug，覆盖块不会生效）。
func pageScope(path string) string {
switch {
case path == "/":
return "home"
case path == "/explore" || strings.HasPrefix(path, "/explore/"):
return "explore"
case path == "/login" || strings.HasPrefix(path, "/login/"),
path == "/register" || strings.HasPrefix(path, "/register/"):
return "auth"
case path == "/user" || strings.HasPrefix(path, "/user/"):
// 题目/私聊管理列表、数据面板都是「读数据」的页面，和「设置表单」的信息密度差很多，
// 装饰要分开配：admin 更该退到背景，profile 可以保留一点氛围。
if strings.HasPrefix(path, "/user/questions") || strings.HasPrefix(path, "/user/votes") ||
strings.HasPrefix(path, "/user/insights") {
return "admin"
}
return "profile"
case strings.HasPrefix(path, "/_/"):
// /_/{domain} → 箱主页（问题列表）
// /_/{domain}/{qid} → 单个问题
// /_/{domain}/tag/xxx → 仍是箱主页
rest := strings.Trim(path[len("/_/"):], "/")
parts := strings.Split(rest, "/")
if len(parts) == 2 && isAllDigits(parts[1]) {
return "question"
}
return "box"
case path == "/vote" || strings.HasPrefix(path, "/vote/"):
return "vote"
}
return ""
}
func isAllDigits(s string) bool {
if s == "" {
return false
}
for _, r := range s {
if r < '0' || r > '9' {
return false
}
}
return true
}
internal/context/context_test.go
-65
View File
@@ -1,65 +0,0 @@
package context
import "testing"
// 主题作用域：/user 后台必须命中（否则设置页、题目管理页拿不到自己的主题），
// 其余路径不得命中（提问箱页面由 question.Pager 按箱主注入，公开页保持站点默认）。
func TestIsThemeScope(t *testing.T) {
cases := map[string]bool{
"/user": true,
"/user/": true,
"/user/profile": true,
"/user/questions": true,
"/user/votes/1/results": true,
"/username": false, // 前缀相近但不是用户后台
"/_/admin6": false,
"/_/admin6/share-card": false,
"/": false,
"/explore": false,
"/vote/abc": false,
"/api/v1/user/admin6": false,
"/api/v1/user": false,
"/deactivated": false,
}
for path, want := range cases {
if got := isThemeScope(path); got != want {
t.Errorf("isThemeScope(%q) = %v, want %v", path, got, want)
}
}
}
// 页面作用域：主题按页面分别摆装饰靠这个值区分。
// 重点是把「箱主页 / 单题页 / 题目管理页」分清楚 —— 三者路径前缀很像。
func TestPageScope(t *testing.T) {
cases := map[string]string{
"/": "home",
"/explore": "explore",
"/explore/users": "explore",
"/login": "auth",
"/register": "auth",
"/user": "profile",
"/user/profile": "profile",
"/user/questions": "admin", // 题目列表：信息密，装饰要退
"/user/votes/1/results": "admin",
"/user/insights": "admin", // 数据面板同属「读数据」
"/_/admin6": "box",
"/_/admin6/": "box",
"/_/admin6/tag/杂谈": "box",
"/_/admin6/answer": "box", // 非数字段 → 不是单题页
"/_/admin6/123": "question",
"/_/admin6/123/": "question",
"/vote/abc123": "vote",
"/username": "",
"/_": "",
"/deactivated": "",
"/api/v1/user/admin6": "",
"/api/v1/user/admin6/questions": "",
}
for path, want := range cases {
if got := pageScope(path); got != want {
t.Errorf("pageScope(%q) = %q, want %q", path, got, want)
}
}
}
internal/db/analytics.go
-370
View File
@@ -1,370 +0,0 @@
// Copyright 2022 E99p1ant. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"fmt"
"time"
"github.com/pkg/errors"
"gorm.io/gorm"
)
// SiteAnalyticsStore 提供「全站公开数据页」所需的聚合查询。
//
// 与 internal/stats 的分工：本层只做数据库聚合（纯查询，不缓存、不生成文案），
// 缓存、补齐空日期与展示模型都在 stats 层。这样聚合 SQL 可以脱离 HTTP 单测。
type SiteAnalyticsStore interface {
SiteAnalytics(ctx context.Context, now time.Time) (*SiteAnalytics, error)
// TodayCounts 单独取「今日提问 / 今日回答」。
//
// 它们刻意不进 SiteAnalytics：整页聚合一整天只算一次，而这两个数要跟着
// 页面上的「实时」说明走，必须每次（或每隔几十秒）重新取。
TodayCounts(ctx context.Context, since time.Time) (questions, answers int64, err error)
}
// Analytics 全站聚合查询的包级入口，在 Init 中随其他 store 一起初始化。
var Analytics SiteAnalyticsStore
// SiteAnalytics 是一次全站聚合的原始结果，所有计数都是「累及至今」或「窗口内」的口径，
// 具体窗口由调用方传入的 now 决定（见 stats 包的 Overview）。
type SiteAnalytics struct {
RegisteredUsers int64
TotalQuestions int64
Answered int64
Private int64
Read int64
Anonymous int64
ActiveBoxes int64 // 至少收到过一条提问的箱主数
AnsweringBoxes int64 // 至少回答过一条提问的箱主数
TotalMessages int64
LastQuestionAt *time.Time
LastAnswerAt *time.Time
Daily []CountPoint // 近 30 天（按日）
Monthly []CountPoint // 近 12 个月（按月）
// Heatmap 一周 7 天 × 24 小时的提问量，下标 0 为周日（与 EXTRACT(DOW) 对齐）。
Heatmap [7][24]int64
HeatmapDays int // Heatmap 的统计窗口天数，用于在页面上说明口径
LengthBins [6]int64 // 提问字数分布
ReplyBins [6]int64 // 回答耗时分布（仅统计已回答的提问）
}
// CountPoint 一个分组键上的计数，Key 已由数据库格式化成可直接展示的字符串。
type CountPoint struct {
Key string
N int64
}
func NewSiteAnalyticsStore(db *gorm.DB) SiteAnalyticsStore {
return &siteAnalytics{db}
}
type siteAnalytics struct {
*gorm.DB
}
const (
// 趋势窗口：近 30 天按日、近 12 个月按月。
analyticsDailyDays = 30
analyticsMonths = 12
// 热力图窗口：一年太贵（全表聚合），半年足以代表「全站习惯」。
analyticsHeatmapDays = 180
// 字数分桶上限（左闭右开），最后一桶为 500 以上。
lengthBinExpr = `CASE
WHEN CHAR_LENGTH(content) < 20 THEN 0
WHEN CHAR_LENGTH(content) < 50 THEN 1
WHEN CHAR_LENGTH(content) < 100 THEN 2
WHEN CHAR_LENGTH(content) < 200 THEN 3
WHEN CHAR_LENGTH(content) < 500 THEN 4
ELSE 5 END`
)
// analyticsDialect 把两套数据库里含义相同、写法不同的表达式收敛到一处。
//
// 项目实际部署用 PostgreSQL（见 Init 的索引分支），MySQL 分支只是保留可用性：
// 配置切到 MySQL 时不应整页 500，而应安静地少几个数。
type analyticsDialect struct {
day string
month string
dow string
hour string
replyMin string
}
func analyticsDialectFor(db *gorm.DB, at time.Time) analyticsDialect {
tz := analyticsTZOffset(at)
if db.Dialector.Name() == "mysql" {
// MySQL 的 DATETIME 不带时区，驱动按 DSN 的 loc（默认 UTC）写入，
// 因此库里存的是 UTC 墙钟，CONVERT_TZ 再搬到进程时区。用偏移而不是
// 时区名：CONVERT_TZ 用时区名要求 mysql.time_zone* 表已导入。
conv := func(col string) string {
return fmt.Sprintf("CONVERT_TZ(%s, '+00:00', '%s')", col, tz)
}
day := conv("created_at")
return analyticsDialect{
day: fmt.Sprintf("DATE_FORMAT(%s, '%%Y-%%m-%%d')", day),
month: fmt.Sprintf("DATE_FORMAT(%s, '%%Y-%%m')", day),
dow: fmt.Sprintf("(DAYOFWEEK(%s) - 1)", day),
hour: fmt.Sprintf("HOUR(%s)", day),
// 回答耗时以 answered_at 为准。历史行该列为空（加列之前回答的），
// 只能退回 updated_at —— 那部分含已读/置顶带来的误差，无法追溯修正。
replyMin: "TIMESTAMPDIFF(MINUTE, created_at, COALESCE(answered_at, updated_at))",
}
}
// PostgreSQL：EXTRACT 返回 numeric，显式转 int 以免扫描进 int64 时类型不匹配。
loc := func(col string) string { return analyticsLocalize(col, at) }
return analyticsDialect{
day: fmt.Sprintf("to_char(%s, 'YYYY-MM-DD')", loc("created_at")),
month: fmt.Sprintf("to_char(%s, 'YYYY-MM')", loc("created_at")),
dow: fmt.Sprintf("CAST(EXTRACT(DOW FROM %s) AS INTEGER)", loc("created_at")),
hour: fmt.Sprintf("CAST(EXTRACT(HOUR FROM %s) AS INTEGER)", loc("created_at")),
replyMin: "CAST(EXTRACT(EPOCH FROM (COALESCE(answered_at, updated_at) - created_at)) / 60 AS INTEGER)",
}
}
// analyticsLocalize 把带时区的列转成「Go 进程所在时区的墙钟时间」再参与日期分组。
//
// 不能依赖数据库会话时区：PG 官方镜像默认 timezone=UTC，而 Go 侧按容器本地时区
// （Dockerfile 里写的是 Asia/Shanghai）切「今天」。两边不一致时，日报表与热力图会
// 整体偏 8 小时 —— 中国时间 0–8 点的提问被算进前一天，且和页面顶部「今日」对不上。
// 这类偏差肉眼看不出来（数字本身都合理），只能靠显式换算消除。
//
// 用固定偏移而不是 IANA 名：Go 在容器未设 TZ 时会给出 "Local"，PG 不认这个名字。
// 中国无夏令时，固定偏移与真实时区完全等价；有夏令时的部署在窗口内可能差 1 小时。
func analyticsLocalize(col string, at time.Time) string {
return fmt.Sprintf("%s AT TIME ZONE INTERVAL '%s'", col, analyticsTZOffset(at))
}
// analyticsTZOffset 返回 +08:00 这样的偏移字面量。
func analyticsTZOffset(at time.Time) string {
_, off := at.Zone()
sign := "+"
if off < 0 {
sign, off = "-", -off
}
return fmt.Sprintf("%s%02d:%02d", sign, off/3600, off%3600/60)
}
func (db *siteAnalytics) SiteAnalytics(ctx context.Context, now time.Time) (*SiteAnalytics, error) {
loc := now.Location()
startOfDay := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, loc)
dailySince := startOfDay.AddDate(0, 0, -(analyticsDailyDays - 1))
// 先归到当月 1 号再回退，避免月底 AddDate 溢出（3-31 减 11 个月会滚到 3-03）。
monthSince := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, loc).AddDate(0, -(analyticsMonths - 1), 0)
heatmapSince := startOfDay.AddDate(0, 0, -analyticsHeatmapDays)
out := &SiteAnalytics{HeatmapDays: analyticsHeatmapDays}
if err := db.aggregateTotals(ctx, out); err != nil {
return nil, err
}
if err := db.aggregateTrends(ctx, out, now, dailySince, monthSince); err != nil {
return nil, err
}
if err := db.aggregateHeatmap(ctx, out, now, heatmapSince); err != nil {
return nil, err
}
if err := db.aggregateContent(ctx, out); err != nil {
return nil, err
}
if err := db.WithContext(ctx).Model(&User{}).Count(&out.RegisteredUsers).Error; err != nil {
return nil, errors.Wrap(err, "count registered users")
}
if err := db.WithContext(ctx).Model(&Message{}).Count(&out.TotalMessages).Error; err != nil {
return nil, errors.Wrap(err, "count messages")
}
// 「今日」两项不在这里查：本函数的结果整天缓存，把会变的数字放进来
// 会让页面顶着一个「实时」的说明显示一整天不变的值。见 TodayCounts。
return out, nil
}
// TodayCounts 取今日提问数与今日回答数。
//
// 口径：
// - 今日提问 = created_at 落在今天的提问，走 idx_questions_created_at；
// - 今日回答 = answered_at 落在今天的提问，即「今天首次被回答」。
// 不能拿 updated_at 当回答时间：置顶、公开/私密切换、标记已读都会刷新它
// （GORM 的 Update 一律更新 updated_at），箱主晚上整理一批三个月前的老问题
// —— 一次回答都没有 —— 页面上「今日回答」就会凭空多出几十条。
//
// answered_at 没有索引，这一条是全表过滤（与改动前的 updated_at 同级别）；
// 十万行量级约几十毫秒，页面另有 60 秒缓存，够用。真慢了再加
// idx_questions_answered_at，不必为这个查询动表结构。
func (db *siteAnalytics) TodayCounts(ctx context.Context, since time.Time) (int64, int64, error) {
var questions, answers int64
if err := db.WithContext(ctx).Model(&Question{}).
Where("created_at >= ?", since).Count(&questions).Error; err != nil {
return 0, 0, errors.Wrap(err, "count today's questions")
}
if err := db.WithContext(ctx).Model(&Question{}).
Where("answer <> '' AND answered_at >= ?", since).Count(&answers).Error; err != nil {
return 0, 0, errors.Wrap(err, "count today's answers")
}
return questions, answers, nil
}
// aggregateTotals 用一条 SQL 取回所有「不分时间窗口」的计数。
//
// 用 SUM(CASE WHEN ...) 而不是 COUNT(*) FILTER (WHERE ...)：前者 MySQL 也支持，
// 后者只在 PostgreSQL 上可用。
func (db *siteAnalytics) aggregateTotals(ctx context.Context, out *SiteAnalytics) error {
var row struct {
Total int64
Answered int64
Private int64
Read int64
Anonymous int64
ActiveBoxes int64 `gorm:"column:active_boxes"`
AnsweringBoxes int64 `gorm:"column:answering_boxes"`
LastQ *time.Time `gorm:"column:last_q"`
LastA *time.Time `gorm:"column:last_a"`
}
err := db.WithContext(ctx).Model(&Question{}).
Select(`COUNT(*) AS total,
COALESCE(SUM(CASE WHEN answer <> '' THEN 1 ELSE 0 END), 0) AS answered,
COALESCE(SUM(CASE WHEN is_private THEN 1 ELSE 0 END), 0) AS private,
COALESCE(SUM(CASE WHEN is_read OR answer <> '' THEN 1 ELSE 0 END), 0) AS read,
COALESCE(SUM(CASE WHEN asker_user_id = 0 THEN 1 ELSE 0 END), 0) AS anonymous,
COUNT(DISTINCT user_id) AS active_boxes,
COUNT(DISTINCT CASE WHEN answer <> '' THEN user_id END) AS answering_boxes,
MAX(created_at) AS last_q,
MAX(CASE WHEN answer <> '' THEN COALESCE(answered_at, updated_at) END) AS last_a`).
Scan(&row).Error
if err != nil {
return errors.Wrap(err, "aggregate question totals")
}
out.TotalQuestions = row.Total
out.Answered = row.Answered
out.Private = row.Private
out.Read = row.Read
out.Anonymous = row.Anonymous
out.ActiveBoxes = row.ActiveBoxes
out.AnsweringBoxes = row.AnsweringBoxes
out.LastQuestionAt = row.LastQ
out.LastAnswerAt = row.LastA
return nil
}
// aggregateTrends 按日与按月各取一次计数。未被 GROUP BY 覆盖的空日期由 stats 层补齐。
func (db *siteAnalytics) aggregateTrends(ctx context.Context, out *SiteAnalytics, now, dailySince, monthSince time.Time) error {
d := analyticsDialectFor(db.DB, now)
var daily []struct {
Key string
N int64
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(d.day+" AS key, COUNT(*) AS n").
Where("created_at >= ?", dailySince).
Group(d.day).Order(d.day).
Scan(&daily).Error; err != nil {
return errors.Wrap(err, "aggregate daily trend")
}
for _, row := range daily {
out.Daily = append(out.Daily, CountPoint{Key: row.Key, N: row.N})
}
var monthly []struct {
Key string
N int64
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(d.month+" AS key, COUNT(*) AS n").
Where("created_at >= ?", monthSince).
Group(d.month).Order(d.month).
Scan(&monthly).Error; err != nil {
return errors.Wrap(err, "aggregate monthly trend")
}
for _, row := range monthly {
out.Monthly = append(out.Monthly, CountPoint{Key: row.Key, N: row.N})
}
return nil
}
func (db *siteAnalytics) aggregateHeatmap(ctx context.Context, out *SiteAnalytics, now, since time.Time) error {
d := analyticsDialectFor(db.DB, now)
var rows []struct {
Dow int
Hr int
N int64
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(d.dow+" AS dow, "+d.hour+" AS hr, COUNT(*) AS n").
Where("created_at >= ?", since).
Group(d.dow + ", " + d.hour).
Scan(&rows).Error; err != nil {
return errors.Wrap(err, "aggregate weekday/hour heatmap")
}
for _, row := range rows {
// 越界值直接丢弃：MySQL 的 DAYOFWEEK 或异常时区数据都可能给出 7 以上的下标，
// 落进固定数组会 panic，而这份数据只影响一张图，不值得让整页失败。
if row.Dow < 0 || row.Dow > 6 || row.Hr < 0 || row.Hr > 23 {
continue
}
out.Heatmap[row.Dow][row.Hr] = row.N
}
return nil
}
func (db *siteAnalytics) aggregateContent(ctx context.Context, out *SiteAnalytics) error {
// 内容分布只用时长差值，不涉及日期分组，时区不影响结果。
d := analyticsDialectFor(db.DB, time.Now())
var lengths []struct {
Bin int
N int64
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(lengthBinExpr + " AS bin, COUNT(*) AS n").
Group(lengthBinExpr).
Scan(&lengths).Error; err != nil {
return errors.Wrap(err, "aggregate content length distribution")
}
for _, row := range lengths {
if row.Bin >= 0 && row.Bin < len(out.LengthBins) {
out.LengthBins[row.Bin] = row.N
}
}
// 回答耗时：只用已回答的提问，按分钟分桶。
// 口径注意：updated_at 也会被置顶等写操作刷新，因此这里算出的耗时偏大；
// 展示时只呈现「24 小时内回答占比」这类粗粒度结论，不宣称精确中位数。
replyBinExpr := fmt.Sprintf(`CASE
WHEN %[1]s < 60 THEN 0
WHEN %[1]s < 360 THEN 1
WHEN %[1]s < 1440 THEN 2
WHEN %[1]s < 4320 THEN 3
WHEN %[1]s < 10080 THEN 4
ELSE 5 END`, d.replyMin)
var replies []struct {
Bin int
N int64
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(replyBinExpr + " AS bin, COUNT(*) AS n").
Where("answer <> ''").
Group(replyBinExpr).
Scan(&replies).Error; err != nil {
return errors.Wrap(err, "aggregate reply latency distribution")
}
for _, row := range replies {
if row.Bin >= 0 && row.Bin < len(out.ReplyBins) {
out.ReplyBins[row.Bin] = row.N
}
}
return nil
}
internal/db/analytics_test.go
-184
View File
@@ -1,184 +0,0 @@
// Copyright 2022 E99p1ant. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"strings"
"testing"
"time"
"github.com/stretchr/testify/require"
)
// TestSiteAnalytics 验证 /stats 页的聚合口径。
//
// 这里刻意连真库跑而不是塞 mock：整段都是数据库方言相关的 SQL
// （to_char / EXTRACT / CHAR_LENGTH / SUM(CASE WHEN)），
// 对着 mock 断言等于什么都没验证。
func TestSiteAnalytics(t *testing.T) {
t.Parallel()
db, cleanup := newTestDB(t)
t.Cleanup(func() {
if err := cleanup("users", "questions", "messages"); err != nil {
t.Fatal(err)
}
})
ctx := context.Background()
now := time.Now()
store := NewSiteAnalyticsStore(db)
questions := NewQuestionsStore(db)
require.NoError(t, db.Create(&User{UID: "u1", Name: "box", Domain: "boxa", Email: "[email protected]"}).Error)
// 一条登录用户提的、已回答的长问题
answered, err := questions.Create(ctx, CreateQuestionOptions{
UserID: 1, Content: strings.Repeat("字", 120), FromIP: "1.1.1.1", AskerUserID: 7,
})
require.NoError(t, err)
require.NoError(t, questions.AnswerByID(ctx, answered.ID, "答案"))
// 一条匿名提的私密短问题，未读未答
_, err = questions.Create(ctx, CreateQuestionOptions{
UserID: 1, Content: "短问题", FromIP: "1.1.1.2", IsPrivate: true,
})
require.NoError(t, err)
// 一条被软删除的：不该出现在任何数字里
deleted, err := questions.Create(ctx, CreateQuestionOptions{
UserID: 1, Content: "会被删掉", FromIP: "1.1.1.3",
})
require.NoError(t, err)
require.NoError(t, questions.DeleteByID(ctx, deleted.ID))
got, err := store.SiteAnalytics(ctx, now)
require.NoError(t, err)
// 计数
require.EqualValues(t, 1, got.RegisteredUsers)
require.EqualValues(t, 2, got.TotalQuestions, "软删除的提问不能计入总数")
require.EqualValues(t, 1, got.Answered)
require.EqualValues(t, 1, got.Private)
require.EqualValues(t, 1, got.Read, "已回答的提问恒为已读")
require.EqualValues(t, 1, got.Anonymous)
require.EqualValues(t, 1, got.ActiveBoxes)
require.EqualValues(t, 1, got.AnsweringBoxes)
// 今日（提问是刚才写的，必然落在今天）—— 单独取，不随整页聚合缓存
dayStart := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location())
todayQ, todayA, err := store.TodayCounts(ctx, dayStart)
require.NoError(t, err)
require.EqualValues(t, 2, todayQ)
require.EqualValues(t, 1, todayA)
// 日/月趋势里能找到今天与本月
today := now.Format("2006-01-02")
require.EqualValues(t, 2, countOf(got.Daily, today))
require.EqualValues(t, 2, countOf(got.Monthly, now.Format("2006-01")))
// 热力图：两条提问都发生在当前这一小时
dow := int(now.Weekday()) // Go 的 Weekday 与 EXTRACT(DOW) 都是周日 0
require.EqualValues(t, 2, got.Heatmap[dow][now.Hour()])
// 字数分桶：120 字落在 100–199（下标 3），"短问题" 3 字落在 <20（下标 0）
require.EqualValues(t, 1, got.LengthBins[0])
require.EqualValues(t, 1, got.LengthBins[3])
// 回答耗时：刚回答完，落在 1 小时内（下标 0）；未回答的不计入
require.EqualValues(t, 1, got.ReplyBins[0])
var replyTotal int64
for _, n := range got.ReplyBins {
replyTotal += n
}
require.EqualValues(t, 1, replyTotal, "耗时分布只统计已回答的提问")
// 最后时间戳
require.NotNil(t, got.LastQuestionAt)
require.NotNil(t, got.LastAnswerAt)
}
// TestTodayAnswersIgnoreNonAnswerWrites 「今日回答」只数今天首次被回答的提问。
//
// 原来按 updated_at 算，而置顶、公开/私密切换都会刷新 updated_at：
// 箱主今晚整理一批三个月前的老问题（一次回答都没有），页面上「今日回答」
// 就凭空多出几十条。改成 answered_at 后，只有真的发生了「首次回答」才算。
func TestTodayAnswersIgnoreNonAnswerWrites(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
store := NewSiteAnalyticsStore(conn)
questions := NewQuestionsStore(conn)
ctx := context.Background()
now := time.Now()
dayStart := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location())
old := now.Add(-72 * time.Hour)
// 三天前提出并回答的历史问题
legacy, err := questions.Create(ctx, CreateQuestionOptions{UserID: 1, Content: "旧问题", FromIP: "1.1.1.1"})
require.NoError(t, err)
require.NoError(t, questions.AnswerByID(ctx, legacy.ID, "旧答案"))
// 把三个时间都冻回三天前（AnswerByID 会把 answered_at / updated_at 刷成当下）
require.NoError(t, conn.Model(&Question{}).Where("id = ?", legacy.ID).UpdateColumn("created_at", old).Error)
require.NoError(t, conn.Model(&Question{}).Where("id = ?", legacy.ID).UpdateColumn("answered_at", old).Error)
require.NoError(t, conn.Model(&Question{}).Where("id = ?", legacy.ID).UpdateColumn("updated_at", old).Error)
// 今天真的答了一条
fresh, err := questions.Create(ctx, CreateQuestionOptions{UserID: 1, Content: "新问题", FromIP: "1.1.1.2"})
require.NoError(t, err)
require.NoError(t, questions.AnswerByID(ctx, fresh.ID, "今天的答案"))
_, answers, err := store.TodayCounts(ctx, dayStart)
require.NoError(t, err)
require.EqualValues(t, 1, answers)
// 箱主今晚翻旧账：置顶、切私密、再切回公开 —— 一次回答都没发生
require.NoError(t, questions.SetPinned(ctx, legacy.ID, true))
require.NoError(t, questions.SetPrivate(ctx, legacy.ID))
require.NoError(t, questions.SetPublic(ctx, legacy.ID))
_, answers, err = store.TodayCounts(ctx, dayStart)
require.NoError(t, err)
require.EqualValues(t, 1, answers, "置顶 / 公开切换不该算成「今日回答」")
}
// TestSiteAnalyticsEmpty 空库不应报错，也不应把零值算成异常。
func TestSiteAnalyticsEmpty(t *testing.T) {
t.Parallel()
db, cleanup := newTestDB(t)
t.Cleanup(func() {
if err := cleanup("users", "questions", "messages"); err != nil {
t.Fatal(err)
}
})
got, err := NewSiteAnalyticsStore(db).SiteAnalytics(context.Background(), time.Now())
require.NoError(t, err)
require.Zero(t, got.TotalQuestions)
require.Zero(t, got.RegisteredUsers)
require.Nil(t, got.LastQuestionAt)
require.Nil(t, got.LastAnswerAt)
var heatTotal int64
for _, row := range got.Heatmap {
for _, n := range row {
heatTotal += n
}
}
require.Zero(t, heatTotal)
}
func countOf(points []CountPoint, key string) int64 {
for _, p := range points {
if p.Key == key {
return p.N
}
}
return 0
}
internal/db/answered_at_test.go
-202
View File
@@ -1,202 +0,0 @@
// Copyright 2022 E99p1ant. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"testing"
"time"
"github.com/stretchr/testify/require"
)
// TestAnsweredAtOnlySetOnFirstAnswer 回答时间只记一次。
//
// 背景：GORM 的 Update 会自动刷新 updated_at，而已读、置顶、公开/私密切换
// 都走 Update。若拿 updated_at 当回答时间，回答完再点一次「已读」，
// 耗时就会从几分钟变成几十天 —— 线上那份「6 条超过 7 天」的数据就是这么来的。
func TestAnsweredAtOnlySetOnFirstAnswer(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
createdAt := time.Now().Add(-72 * time.Hour).Truncate(time.Second)
q := Question{UserID: 1, Content: "hello", CreatedAt: createdAt, UpdatedAt: createdAt}
require.NoError(t, conn.Create(&q).Error)
store := NewQuestionsStore(conn)
require.NoError(t, store.AnswerByID(context.Background(), q.ID, "first"))
var got Question
require.NoError(t, conn.First(&got, q.ID).Error)
require.NotNil(t, got.AnsweredAt, "首次回答必须记下 answered_at")
firstAt := *got.AnsweredAt
require.WithinDuration(t, time.Now(), firstAt, time.Minute)
// 改写回答：answered_at 不能被重置，否则「回答耗时」会跟着编辑动作变大。
require.NoError(t, store.AnswerByID(context.Background(), q.ID, "edited"))
require.NoError(t, conn.First(&got, q.ID).Error)
require.NotNil(t, got.AnsweredAt)
require.Equal(t, firstAt.Unix(), got.AnsweredAt.Unix(), "改写回答不该重置 answered_at")
}
// TestAnsweredAtSetWhenAnsweringAsPrivate 强制私密那条 UPDATE 同样要记时间。
func TestAnsweredAtSetWhenAnsweringAsPrivate(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
q := Question{UserID: 1, Content: "secret"}
require.NoError(t, conn.Create(&q).Error)
require.NoError(t, NewQuestionsStore(conn).AnswerByIDPrivate(context.Background(), q.ID, "answer"))
var got Question
require.NoError(t, conn.First(&got, q.ID).Error)
require.NotNil(t, got.AnsweredAt)
require.True(t, got.IsPrivate)
require.True(t, got.IsRead)
}
// TestReplyBinsUseAnsweredAt 回答耗时以 answered_at 为准，不受后来的「已读」影响。
//
// 构造：72 小时前提问、10 分钟前回答（落第一档）；但 updated_at 被改成当下
// （相当于回答完又被读了一次），差值是 72 小时 = 4320 分钟，正好落到第四档。
// 若仍在用 updated_at，这条会进第四档而不是第一档。
func TestReplyBinsUseAnsweredAt(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
now := time.Now()
createdAt := now.Add(-72 * time.Hour)
answeredAt := createdAt.Add(10 * time.Minute) // 提问后 10 分钟回答 → 第一档
q := Question{UserID: 1, Content: "hi", CreatedAt: createdAt, UpdatedAt: createdAt}
require.NoError(t, conn.Create(&q).Error)
// 直接写列，绕开 GORM 的 UpdatedAt 自动更新。
require.NoError(t, conn.Exec(
"UPDATE questions SET answer = ?, is_read = ?, answered_at = ?, updated_at = ? WHERE id = ?",
"answer", true, answeredAt, now, q.ID).Error)
got, err := NewSiteAnalyticsStore(conn).SiteAnalytics(context.Background(), now)
require.NoError(t, err)
var total int64
for _, n := range got.ReplyBins {
total += n
}
require.EqualValues(t, 1, total)
require.EqualValues(t, 1, got.ReplyBins[0], "10 分钟的回答应落在第一档")
require.EqualValues(t, 0, got.ReplyBins[4], "不该被 pushed 到当下的 updated_at 带偏")
// 「最后一条回答」同理：取 answered_at 而不是被刷新过的 updated_at。
require.NotNil(t, got.LastAnswerAt)
require.WithinDuration(t, answeredAt, *got.LastAnswerAt, time.Minute)
}
// TestReplyBinsFallBackToUpdatedAt 加列之前回答的历史行 answered_at 为空，
// 退回 updated_at，不能让这些提问从分布里消失。
func TestReplyBinsFallBackToUpdatedAt(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
now := time.Now()
// 10 天前提问、9 天前处理：差值 24 小时（1440 分钟），落在第三档。
createdAt := now.Add(-10 * 24 * time.Hour)
updatedAt := now.Add(-9 * 24 * time.Hour)
q := Question{UserID: 1, Content: "old", CreatedAt: createdAt, UpdatedAt: createdAt}
require.NoError(t, conn.Create(&q).Error)
require.NoError(t, conn.Exec(
"UPDATE questions SET answer = ?, answered_at = NULL, updated_at = ? WHERE id = ?",
"old answer", updatedAt, q.ID).Error)
got, err := NewSiteAnalyticsStore(conn).SiteAnalytics(context.Background(), now)
require.NoError(t, err)
require.EqualValues(t, 1, got.Answered)
require.EqualValues(t, 1, got.ReplyBins[3], "历史行应退回 updated_at 计入分布")
}
// TestQuestionStatsLastAnswerIgnoresLaterEdits 「最后一个回答」不能跟着置顶/公开切换跑。
//
// QuestionStats 仍被公开接口 /api/v1/site-stats 使用。它原来取 MAX(updated_at)，
// 而 updated_at 会被 SetPinned / SetPrivate / SetPublic / SetRead 刷新，
// 于是箱主整理一下旧问题（哪怕一次回答都没发生），接口就说「刚刚有人回答了」。
func TestQuestionStatsLastAnswerIgnoresLaterEdits(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
store := NewQuestionsStore(conn)
ctx := context.Background()
now := time.Now().Truncate(time.Second)
answeredAt := now.Add(-9 * 24 * time.Hour)
q := Question{UserID: 1, Content: "q", CreatedAt: answeredAt.Add(-time.Hour), UpdatedAt: answeredAt}
require.NoError(t, conn.Create(&q).Error)
require.NoError(t, store.AnswerByID(ctx, q.ID, "answer"))
// AnswerByID 会把两个时间刷成当下，冻回真实回答时刻（模拟一条正常的历史数据）。
require.NoError(t, conn.Model(&Question{}).Where("id = ?", q.ID).
UpdateColumn("updated_at", answeredAt).Error)
require.NoError(t, conn.Model(&Question{}).Where("id = ?", q.ID).
UpdateColumn("answered_at", answeredAt).Error)
// 全是「没回答任何东西」的写操作。
require.NoError(t, store.SetPinned(ctx, q.ID, true))
require.NoError(t, store.SetPrivate(ctx, q.ID))
require.NoError(t, store.SetPublic(ctx, q.ID))
require.NoError(t, store.SetRead(ctx, q.ID))
qs, err := store.QuestionStats(ctx)
require.NoError(t, err)
require.NotNil(t, qs.LastAnswerAt)
require.WithinDuration(t, answeredAt, *qs.LastAnswerAt, time.Minute,
"最后一个回答被置顶/公开切换刷新过的 updated_at 带偏了")
}
// TestQuestionStatsLastAnswerFallsBackToUpdatedAt 加列之前的历史行 answered_at 为空，
// 退回 updated_at —— 与改动前的行为一致，不能让这些行从统计里消失。
func TestQuestionStatsLastAnswerFallsBackToUpdatedAt(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
answeredAt := time.Now().Add(-5 * 24 * time.Hour).Truncate(time.Second)
require.NoError(t, conn.Exec(
"INSERT INTO questions (user_id, content, answer, is_private, is_read, is_pinned, created_at, updated_at) VALUES (1,'legacy','a',false,true,false,?,?)",
answeredAt.Add(-time.Hour), answeredAt).Error)
qs, err := NewQuestionsStore(conn).QuestionStats(context.Background())
require.NoError(t, err)
require.NotNil(t, qs.LastAnswerAt)
require.WithinDuration(t, answeredAt, *qs.LastAnswerAt, time.Second)
}
// TestBackfillAnsweredAt 历史行回填：拿 updated_at 冻结一次，之后不再随已读漂移。
func TestBackfillAnsweredAt(t *testing.T) {
conn, clean := newTestDB(t)
defer clean("questions")
// 列由 AutoMigrate 建好，HasColumn 必须能认出来（启动时靠它判断「是不是刚加列」）。
require.True(t, conn.Migrator().HasColumn(&Question{}, "answered_at"))
now := time.Now()
createdAt := now.Add(-20 * 24 * time.Hour)
answeredAtOld := now.Add(-19 * 24 * time.Hour)
// 一条历史已回答（answered_at 为空），一条未回答（不该被回填）。
require.NoError(t, conn.Exec(
"INSERT INTO questions (user_id, content, answer, is_private, is_read, is_pinned, created_at, updated_at) VALUES (1,'old','a',false,true,false,?,?)",
createdAt, answeredAtOld).Error)
require.NoError(t, conn.Exec(
"INSERT INTO questions (user_id, content, answer, is_private, is_read, is_pinned, created_at, updated_at) VALUES (1,'open','',false,false,false,?,?)",
createdAt, answeredAtOld).Error)
require.NoError(t, backfillAnsweredAt(conn))
var answered Question
require.NoError(t, conn.Where("content = ?", "old").First(&answered).Error)
require.NotNil(t, answered.AnsweredAt)
require.WithinDuration(t, answeredAtOld, *answered.AnsweredAt, time.Second)
var open Question
require.NoError(t, conn.Where("content = ?", "open").First(&open).Error)
require.Nil(t, open.AnsweredAt, "未回答的提问不该被回填")
}
internal/db/ban_record.go
-74
View File
@@ -1,74 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"time"
"gorm.io/gorm"
)
// BanRecord 是一次自动封禁的落库记录。
//
// 为什么需要它：自动封禁的生效状态是**进程内存**里的（见 internal/security/autoban），
// 重启即清零，外部完全看不见。线上出现过「邮件说封了、实际还能访问」的排查困境 ——
// 当时没有任何东西能说明封的是哪个键、因为什么、到什么时候解除，只能靠翻日志猜。
//
// 这张表是「封禁事实」的账本，不参与判定：IsBanned 仍然只读内存，
// 表只用于事后解释与取证。写入失败绝不能影响封禁动作本身。
//
// 增长：每个键在封禁期内不会重复建封（autoban 命中已封禁直接拒绝），
// 所以行数量级 = 封禁次数，不需要自动清理。要清可手动 DELETE。
type BanRecord struct {
ID uint `gorm:"primarykey" json:"id"`
CreatedAt time.Time `gorm:"index" json:"created_at"`
// BanKey 与 autoban.IsBanned 的判断口径完全一致（shared.LimitKey，
// IPv6 折成 /64），否则账本与判定会各说一套。
BanKey string `gorm:"size:64;index" json:"ban_key"`
// Reason 是给人看的原因文案（敏感路径探测 / 蜜罐提交凭据）。
Reason string `gorm:"size:64" json:"reason"`
// DurationMinutes 与 ExpiresAt 一起回答「封多久、什么时候自动解除」。
DurationMinutes int `gorm:"not null;default:0" json:"duration_minutes"`
ExpiresAt time.Time `gorm:"index" json:"expires_at"`
}
// TableName 固定表名，避免 GORM 复数化差异。
func (BanRecord) TableName() string { return "ban_records" }
// BanRecords 自动封禁记录的全局 store，由 db.Init 装配。
var BanRecords BanRecordStore
// BanRecordStore 封禁记录的读写。
type BanRecordStore interface {
// Create 追加一条封禁记录。
Create(ctx context.Context, record *BanRecord) error
// ListSince 返回 since 之后的记录，按时间倒序，最多 limit 条。
ListSince(ctx context.Context, since time.Time, limit int) ([]*BanRecord, error)
}
type banRecords struct {
db *gorm.DB
}
// NewBanRecordsStore 创建封禁记录 store。
func NewBanRecordsStore(db *gorm.DB) BanRecordStore {
return &banRecords{db: db}
}
func (s *banRecords) Create(ctx context.Context, record *BanRecord) error {
return s.db.WithContext(ctx).Create(record).Error
}
func (s *banRecords) ListSince(ctx context.Context, since time.Time, limit int) ([]*BanRecord, error) {
var records []*BanRecord
err := s.db.WithContext(ctx).
Where("created_at >= ?", since).
Order("created_at DESC").
Limit(limit).
Find(&records).Error
return records, err
}
internal/db/ban_record_test.go
-56
View File
@@ -1,56 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"testing"
"time"
"github.com/stretchr/testify/require"
)
// TestBanRecordStore 覆盖自动封禁账本的写入与检索。
//
// 这张表不参与判定（IsBanned 只读内存），所以测试只锁两件事：
// ① 记录能落库并按时间倒序取回；② 到期时间与时长原样保留 ——
// 事后排查全依赖这两个字段回答「封了多久、什么时候解」。
func TestBanRecordStore(t *testing.T) {
database, cleanup := newTestDB(t)
ctx := context.Background()
t.Cleanup(func() {
if err := cleanup("ban_records"); err != nil {
t.Fatal(err)
}
})
store := NewBanRecordsStore(database)
now := time.Now()
rows := []*BanRecord{
{BanKey: "1.2.3.4", Reason: "敏感路径探测", DurationMinutes: 60, ExpiresAt: now.Add(time.Hour), CreatedAt: now.Add(-2 * time.Hour)},
{BanKey: "2001:db8::/64", Reason: "蜜罐提交凭据", DurationMinutes: 1440, ExpiresAt: now.Add(24 * time.Hour), CreatedAt: now.Add(-10 * time.Minute)},
}
for _, r := range rows {
require.NoError(t, store.Create(ctx, r))
}
got, err := store.ListSince(ctx, now.Add(-3*time.Hour), 10)
require.NoError(t, err)
require.Len(t, got, 2)
// 时间倒序：最新的一条在最前
require.Equal(t, "2001:db8::/64", got[0].BanKey)
require.Equal(t, "蜜罐提交凭据", got[0].Reason)
require.Equal(t, 1440, got[0].DurationMinutes)
require.False(t, got[0].ExpiresAt.IsZero(), "到期时间必须保留，否则无法回答「什么时候解」")
// 时间窗过滤生效
recent, err := store.ListSince(ctx, now.Add(-30*time.Minute), 10)
require.NoError(t, err)
require.Len(t, recent, 1)
require.Equal(t, "2001:db8::/64", recent[0].BanKey)
}
internal/db/box_analytics.go
-233
View File
@@ -1,233 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"fmt"
"time"
"github.com/pkg/errors"
"gorm.io/gorm"
)
// BoxAnalyticsStore 是「箱主数据面板」里提问侧的聚合查询（访问侧见 BoxViewsStore）。
//
// 与 SiteAnalyticsStore 分开：那个是站方看的全站数据（不含任何单箱维度），
// 这个是箱主看自己的。两边的 SQL 都按 user_id 走，混在一个接口里会让
// 「全站聚合整天缓存」和「箱主实时看自己的」两种缓存策略纠缠在一起。
type BoxAnalyticsStore interface {
// BoxTrend 返回 [from, to] 内每天的提问数与回答数。只返回有数据的天，缺日由上层补零。
BoxTrend(ctx context.Context, userID uint, from, to time.Time) ([]BoxDayCount, error)
// BoxHours 返回 since 之后该箱收到提问的 24 小时分布（下标 0..23）。
BoxHours(ctx context.Context, userID uint, since time.Time) ([24]int64, error)
// BoxFunnel 返回该箱的提问处理漏斗。
BoxFunnel(ctx context.Context, userID uint) (*BoxFunnel, error)
}
// BoxDayCount 某一天的提问 / 回答计数。
type BoxDayCount struct {
Day time.Time `gorm:"column:day"`
Questions int64 `gorm:"column:questions"`
Answers int64 `gorm:"column:answers"`
}
// BoxFunnel 箱主的提问处理漏斗与响应速度。
type BoxFunnel struct {
Total int64 // 全部提问
Answered int64 // 已回答
ReadOnly int64 // 已读未答
Unread int64 // 未读未答
Private int64 // 私密提问
Anonymous int64 // 匿名（未登录）提问
Pinned int64 // 置顶
// 响应速度只统计已回答且 answered_at 有值的行（历史行退回 updated_at，
// 会有偏高，见 answered_at 的注释）。
RepliedIn24h int64
AvgReplyHour float64
// LastQuestionAt / LastAnswerAt 用于「你多久没看提问箱了」这类提示。
LastQuestionAt *time.Time
LastAnswerAt *time.Time
}
var BoxAnalytics BoxAnalyticsStore
var _ BoxAnalyticsStore = (*boxAnalytics)(nil)
func NewBoxAnalyticsStore(db *gorm.DB) BoxAnalyticsStore {
return &boxAnalytics{db}
}
type boxAnalytics struct {
*gorm.DB
}
func (db *boxAnalytics) BoxTrend(ctx context.Context, userID uint, from, to time.Time) ([]BoxDayCount, error) {
d := analyticsDialectFor(db.DB, from)
from, to = dayOnly(from), dayOnly(to).AddDate(0, 0, 1)
// 提问按 created_at 分组；回答必须按 answered_at（空则退回 updated_at）分组。
// 两条 SQL 的 day 表达式不同：d.day 是 created_at 的日期，回答那条要基于
// COALESCE(answered_at, updated_at)，否则「40 天前创建、昨天才回答」的提问
// 会被排除在窗口外，「今天创建、明天回答」的会被记到今天 —— 趋势图里的
// 「每日回答数」就不是「某天被回答了多少」。
answerDay := analyticsLocalize("COALESCE(answered_at, updated_at)", from)
if db.Dialector.Name() == "mysql" {
answerDay = fmt.Sprintf("DATE_FORMAT(CONVERT_TZ(COALESCE(answered_at, updated_at), '+00:00', '%s'), '%%Y-%%m-%%d')", analyticsTZOffset(from))
} else {
answerDay = fmt.Sprintf("to_char(%s, 'YYYY-MM-DD')", answerDay)
}
// 提问与回答分两条 SQL 再在内存里合并：一条 SQL 里同时按 created_at 和
// answered_at 分组要写成两条子查询再 FULL JOIN，MySQL 没有 FULL JOIN，
// 而两张结果集都很小，合并成本可以忽略。
type row struct {
Key string
N int64
}
var qs, as []row
if err := db.WithContext(ctx).Model(&Question{}).
Select(d.day+" AS key, COUNT(*) AS n").
Where("user_id = ? AND created_at >= ? AND created_at < ?", userID, from, to).
Group(d.day).
Scan(&qs).Error; err != nil {
return nil, errors.Wrap(err, "aggregate box questions by day")
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(answerDay+" AS key, COUNT(*) AS n").
Where("user_id = ? AND answer <> '' AND COALESCE(answered_at, updated_at) >= ? AND COALESCE(answered_at, updated_at) < ?",
userID, from, to).
Group(answerDay).
Scan(&as).Error; err != nil {
return nil, errors.Wrap(err, "aggregate box answers by day")
}
// 用 map 合并，最后仍交给上层按日期补零（上层最清楚要展示哪些天）。
byDay := make(map[string]*BoxDayCount, len(qs))
order := make([]string, 0, len(qs)+len(as))
get := func(key string) *BoxDayCount {
if v, ok := byDay[key]; ok {
return v
}
t, err := time.ParseInLocation("2006-01-02", key, from.Location())
if err != nil {
t = from
}
v := &BoxDayCount{Day: t}
byDay[key] = v
order = append(order, key)
return v
}
for _, r := range qs {
get(r.Key).Questions = r.N
}
for _, r := range as {
get(r.Key).Answers = r.N
}
out := make([]BoxDayCount, 0, len(order))
for _, key := range order {
out = append(out, *byDay[key])
}
return out, nil
}
func (db *boxAnalytics) BoxHours(ctx context.Context, userID uint, since time.Time) ([24]int64, error) {
var out [24]int64
d := analyticsDialectFor(db.DB, since)
var rows []struct {
Hr int
N int64
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(d.hour+" AS hr, COUNT(*) AS n").
Where("user_id = ? AND created_at >= ?", userID, since).
Group(d.hour).
Scan(&rows).Error; err != nil {
return out, errors.Wrap(err, "aggregate box question hours")
}
for _, r := range rows {
if r.Hr >= 0 && r.Hr < 24 {
out[r.Hr] = r.N
}
}
return out, nil
}
func (db *boxAnalytics) BoxFunnel(ctx context.Context, userID uint) (*BoxFunnel, error) {
out := &BoxFunnel{}
var totals struct {
Total int64 `gorm:"column:total"`
Answered int64 `gorm:"column:answered"`
ReadOnly int64 `gorm:"column:read_only"`
Unread int64 `gorm:"column:unread"`
Private int64 `gorm:"column:private"`
Anonymous int64 `gorm:"column:anonymous"`
Pinned int64 `gorm:"column:pinned"`
LastQ *time.Time `gorm:"column:last_q"`
LastA *time.Time `gorm:"column:last_a"`
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(`COUNT(*) AS total,
COALESCE(SUM(CASE WHEN answer <> '' THEN 1 ELSE 0 END), 0) AS answered,
COALESCE(SUM(CASE WHEN answer = '' AND is_read THEN 1 ELSE 0 END), 0) AS read_only,
COALESCE(SUM(CASE WHEN answer = '' AND NOT is_read THEN 1 ELSE 0 END), 0) AS unread,
COALESCE(SUM(CASE WHEN is_private THEN 1 ELSE 0 END), 0) AS private,
COALESCE(SUM(CASE WHEN asker_user_id = 0 THEN 1 ELSE 0 END), 0) AS anonymous,
COALESCE(SUM(CASE WHEN is_pinned THEN 1 ELSE 0 END), 0) AS pinned,
MAX(created_at) AS last_q,
MAX(CASE WHEN answer <> '' THEN COALESCE(answered_at, updated_at) END) AS last_a`).
Where("user_id = ?", userID).
Scan(&totals).Error; err != nil {
return nil, errors.Wrap(err, "aggregate box funnel")
}
out.Total = totals.Total
out.Answered = totals.Answered
out.ReadOnly = totals.ReadOnly
out.Unread = totals.Unread
out.Private = totals.Private
out.Anonymous = totals.Anonymous
out.Pinned = totals.Pinned
out.LastQuestionAt = totals.LastQ
out.LastAnswerAt = totals.LastA
// 响应速度：answered_at 为空的历史行退回 updated_at（口径偏大，只用于展示大致量级）。
replyMinutes := boxReplyMinutesExpr(db.DB, out.LastAnswerAt)
if replyMinutes == "" {
return out, nil
}
var speed struct {
In24h int64 `gorm:"column:in_24h"`
Avg *float64 `gorm:"column:avg_min"`
}
if err := db.WithContext(ctx).Model(&Question{}).
Select(fmt.Sprintf(`COALESCE(SUM(CASE WHEN %[1]s <= 1440 THEN 1 ELSE 0 END), 0) AS in_24h,
AVG(%[1]s) AS avg_min`, replyMinutes)).
Where("user_id = ? AND answer <> ''", userID).
Scan(&speed).Error; err != nil {
return nil, errors.Wrap(err, "aggregate box reply speed")
}
out.RepliedIn24h = speed.In24h
if speed.Avg != nil && *speed.Avg > 0 {
out.AvgReplyHour = *speed.Avg / 60
}
return out, nil
}
// boxReplyMinutesExpr 返回「回答耗时（分钟）」的 SQL 表达式。
//
// 与 analyticsDialectFor 里的 replyMin 口径一致，但这里必须能固定到箱主自己那张表：
// 表达式里出现的列名都来自 questions 表，不需要额外限定。
func boxReplyMinutesExpr(db *gorm.DB, at *time.Time) string {
now := time.Now()
if at != nil {
now = *at
}
d := analyticsDialectFor(db, now)
return d.replyMin
}
internal/db/box_analytics_test.go
-75
View File
@@ -1,75 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"testing"
"time"
"github.com/stretchr/testify/require"
)
// TestBoxTrendAnswerByAnsweredDate 验证「每日回答数」按 answered_at 分组，
// 而不是按 created_at。
//
// 背景：BoxTrend 一度两条 SQL 都复用 created_at 的日期表达式，导致「40 天前创建、
// 昨天才回答」的提问被排除在窗口外（created_at < from），昨天/今天的回答数里
// 根本不出现；「今天创建、明天回答」的又会被记到今天。本测试构造一条
// 「创建日远早于窗口、回答日落在窗口内」的提问，断言它出现在回答日那天。
func TestBoxTrendAnswerByAnsweredDate(t *testing.T) {
db, cleanup := newTestDB(t)
ctx := context.Background()
store := NewBoxAnalyticsStore(db)
t.Cleanup(func() {
_ = cleanup("questions")
})
now := time.Now()
// 窗口 = 最近 7 天
from := now.AddDate(0, 0, -6)
to := now
// 一条 40 天前创建、昨天才回答的提问
answeredAt := now.AddDate(0, 0, -1)
createdAt := now.AddDate(0, 0, -40)
q := &Question{
UserID: 9,
Content: "很久以前问的，昨天才回答",
Answer: "这是回答",
AnsweredAt: &answeredAt,
}
// 直接写 created_at / answered_at，绕过 Create 的自动时间戳
require.NoError(t, db.Model(&Question{}).Create(q).Error)
require.NoError(t, db.Model(&Question{}).Where("id = ?", q.ID).
Updates(map[string]interface{}{
"created_at": createdAt,
"answered_at": answeredAt,
"updated_at": answeredAt,
}).Error)
trend, err := store.BoxTrend(ctx, 9, from, to)
require.NoError(t, err)
// 找到回答日那天（昨天）的计数，答案数应 >= 1
var found bool
for _, d := range trend {
if d.Day.Year() == answeredAt.Year() &&
d.Day.Month() == answeredAt.Month() &&
d.Day.Day() == answeredAt.Day() {
require.GreaterOrEqual(t, d.Answers, int64(1),
"回答应计入 answered_at 那一天，而不是按 created_at 被排除")
found = true
}
// 创建日（40 天前）不应出现在窗口内
if d.Day.Year() == createdAt.Year() &&
d.Day.Month() == createdAt.Month() &&
d.Day.Day() == createdAt.Day() {
t.Errorf("创建日在窗口外，不应出现在趋势里")
}
}
require.True(t, found, "回答日应出现在趋势结果里")
}
internal/db/box_views.go
-234
View File
@@ -1,234 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"time"
"github.com/pkg/errors"
"gorm.io/gorm"
"gorm.io/gorm/clause"
)
// BoxViewsStore 记录「提问箱主页被访问了多少次」。
//
// 为什么要自带一张表：全站数据页（internal/stats）只统计提问/回答/用户，
// 完全没有「有人来看过我的箱」这个维度 —— 箱主看不到自己的任何流量。
// 曾经用过外部计数服务（busuanzi），但它把统计放在第三方、且只能显示两个数，
// 既不可自控也无法按天看趋势，已移除。
//
// 口径与隐私：
// - 一行 = 一个访客在某一天访问了某个箱（唯一索引强制），`views` 是当天的次数；
// - PV = SUM(views)，UV = 行数（因为每行已按访客去重）；
// - 访客标识是 **带日盐的 IP HMAC**，不是 IP 本身，也无法跨天关联同一人。
// 代价是「近 7 天 UV」= 各日 UV 之和，同一人多天来访会被重复计入 —— 这是
// 隐私与准确性的取舍，页面上按「按日去重的独立访客」表述。
type BoxViewsStore interface {
// Record 累加一次访问。实现为单条 UPSERT，并发安全。
Record(ctx context.Context, opts RecordBoxViewOptions) error
// RecordBatch 批量累加（记录器的 flush 用）。单条 SQL，避免 N 次往返。
RecordBatch(ctx context.Context, opts []RecordBoxViewOptions) error
// Daily 返回 [from, to] 内每天的 PV / UV，日期按天升序，缺日不补（由上层补零）。
Daily(ctx context.Context, userID uint, from, to time.Time) ([]BoxViewDay, error)
// TopDays 取历史上 PV 最高的若干天，供「你的最好一天」这类结论使用。
TopDays(ctx context.Context, userID uint, limit int) ([]BoxViewDay, error)
// FirstDay 返回最早有记录的一天；无记录时返回零值时间。
FirstDay(ctx context.Context, userID uint) (time.Time, error)
// Totals 返回全期累计访问量（PV / UV）。
Totals(ctx context.Context, userID uint) (pv, uv int64, err error)
// Purge 删除 before 之前的明细，控制表体积。统计窗口最长 30 天，
// 但「历史最好一天」要看全部，默认保留期由调用方决定（见 insights.Retention）。
Purge(ctx context.Context, before time.Time) (int64, error)
}
// BoxView 一次「访客 × 天 × 箱」的访问记录。
//
// 刻意不内嵌 dbutil.Model：统计流水不需要软删除，而软删除会让唯一索引
// (user_id, viewed_on, visitor) 失效 —— 被「删掉」的行仍然占着槽位，
// 同一访客当天再也插不进去（GORM 软删除 + 唯一索引的经典坑）。
type BoxView struct {
ID uint `gorm:"primarykey"`
UserID uint `gorm:"uniqueIndex:idx_box_views_day_visitor,priority:1;index:idx_box_views_user_day,priority:1"`
ViewedOn time.Time `gorm:"type:date;uniqueIndex:idx_box_views_day_visitor,priority:2;index:idx_box_views_user_day,priority:2"`
Visitor string `gorm:"size:32;uniqueIndex:idx_box_views_day_visitor,priority:3"`
Views int64 `gorm:"not null;default:1"`
CreatedAt time.Time
UpdatedAt time.Time
}
// BoxViewDay 某一天聚合后的访问量。
type BoxViewDay struct {
// Day 当天 0 点（调用方传入的时区）。扫描出来是 date 列，loc 由数据库会话决定，
// 上层只取 Year/Month/Day 拼 key，不依赖时分秒。
Day time.Time `gorm:"column:viewed_on"`
PV int64 `gorm:"column:pv"`
UV int64 `gorm:"column:uv"`
}
type RecordBoxViewOptions struct {
UserID uint
ViewedOn time.Time // 只有年月日有意义，写入前会被截断到当天 0 点
Visitor string
}
var BoxViews BoxViewsStore
var _ BoxViewsStore = (*boxViews)(nil)
func NewBoxViewsStore(db *gorm.DB) BoxViewsStore {
return &boxViews{db}
}
type boxViews struct {
*gorm.DB
}
// dayOnly 把时间截断到当天 0 点。用传入时间的时区，不做 UTC 归一 ——
// 站点按本地时间切「今天」，跨时区归一会让日报表偏一天。
func dayOnly(t time.Time) time.Time {
return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location())
}
func (db *boxViews) Record(ctx context.Context, opts RecordBoxViewOptions) error {
return db.RecordBatch(ctx, []RecordBoxViewOptions{opts})
}
// RecordBatch 单条 INSERT ... ON CONFLICT DO UPDATE 累加。
//
// 冲突时只把 views 加一，visited_at 之外的列不动：同一访客当天第二次访问
// 只是「同一行还来了」，UV 不变、PV +1。
func (db *boxViews) RecordBatch(ctx context.Context, opts []RecordBoxViewOptions) error {
if len(opts) == 0 {
return nil
}
now := time.Now()
rows := make([]BoxView, 0, len(opts))
for _, o := range opts {
if o.UserID == 0 || o.Visitor == "" {
// 缺用户或访客标识的行没有统计价值，直接丢弃：
// 空 Visitor 会让同一箱所有匿名访问挤进同一行，把 UV 压成 1。
continue
}
rows = append(rows, BoxView{
UserID: o.UserID,
ViewedOn: dayOnly(o.ViewedOn),
Visitor: o.Visitor,
Views: 1,
CreatedAt: now,
UpdatedAt: now,
})
}
if len(rows) == 0 {
return nil
}
// 同一批里可能出现同一个 (user, day, visitor) 多次（并发请求攒到一次 flush）：
// PostgreSQL 的 ON CONFLICT 不支持在同一条 INSERT 里两次命中同一行
// （"ON CONFLICT DO UPDATE command cannot affect row a second time"）。
// 所以先在内存里按唯一键合并，把次数累加到 Views 上。
merged := make([]BoxView, 0, len(rows))
index := make(map[[3]interface{}]int, len(rows))
for _, r := range rows {
key := [3]interface{}{r.UserID, r.ViewedOn.Format("2006-01-02"), r.Visitor}
if i, ok := index[key]; ok {
merged[i].Views += r.Views
continue
}
index[key] = len(merged)
merged = append(merged, r)
}
err := db.WithContext(ctx).Clauses(clause.OnConflict{
Columns: []clause.Column{{Name: "user_id"}, {Name: "viewed_on"}, {Name: "visitor"}},
DoUpdates: clause.Assignments(map[string]interface{}{
// 表名限定：PG 里裸 views 在 INSERT ... ON CONFLICT 的 SET 子句里
// 可能被当成目标列的别名解析，加上表名前缀最稳。
"views": gorm.Expr("box_views.views + excluded.views"),
"updated_at": now,
}),
}).Create(&merged).Error
if err != nil {
return errors.Wrap(err, "upsert box views")
}
return nil
}
func (db *boxViews) Daily(ctx context.Context, userID uint, from, to time.Time) ([]BoxViewDay, error) {
var days []BoxViewDay
err := db.WithContext(ctx).Model(&BoxView{}).
Select("viewed_on, SUM(views) AS pv, COUNT(*) AS uv").
Where("user_id = ? AND viewed_on >= ? AND viewed_on <= ?", userID, dayOnly(from), dayOnly(to)).
Group("viewed_on").
Order("viewed_on").
Scan(&days).Error
if err != nil {
return nil, errors.Wrap(err, "aggregate box view days")
}
return days, nil
}
func (db *boxViews) TopDays(ctx context.Context, userID uint, limit int) ([]BoxViewDay, error) {
if limit <= 0 {
limit = 1
}
var days []BoxViewDay
err := db.WithContext(ctx).Model(&BoxView{}).
Select("viewed_on, SUM(views) AS pv, COUNT(*) AS uv").
Where("user_id = ?", userID).
Group("viewed_on").
Order("pv DESC").
Limit(limit).
Scan(&days).Error
if err != nil {
return nil, errors.Wrap(err, "top box view days")
}
return days, nil
}
func (db *boxViews) FirstDay(ctx context.Context, userID uint) (time.Time, error) {
var day *time.Time
err := db.WithContext(ctx).Model(&BoxView{}).
Select("MIN(viewed_on)").
Where("user_id = ?", userID).
Scan(&day).Error
if err != nil {
return time.Time{}, errors.Wrap(err, "first box view day")
}
if day == nil {
return time.Time{}, nil
}
return *day, nil
}
func (db *boxViews) Totals(ctx context.Context, userID uint) (int64, int64, error) {
var row struct {
PV int64 `gorm:"column:pv"`
UV int64 `gorm:"column:uv"`
}
err := db.WithContext(ctx).Model(&BoxView{}).
Select("COALESCE(SUM(views), 0) AS pv, COUNT(*) AS uv").
Where("user_id = ?", userID).
Scan(&row).Error
if err != nil {
return 0, 0, errors.Wrap(err, "total box views")
}
return row.PV, row.UV, nil
}
// Purge 删除 before 之前的访问明细。返回删除行数。
//
// 用 Delete 而非 Unscoped 也没关系 —— BoxView 没有 DeletedAt 字段，
// GORM 看不到软删除标记，会直接发 DELETE。
func (db *boxViews) Purge(ctx context.Context, before time.Time) (int64, error) {
res := db.WithContext(ctx).
Where("viewed_on < ?", dayOnly(before)).
Delete(&BoxView{})
if res.Error != nil {
return 0, errors.Wrap(res.Error, "purge box views")
}
return res.RowsAffected, nil
}
internal/db/box_views_test.go
-131
View File
@@ -1,131 +0,0 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
package db
import (
"context"
"testing"
"time"
"github.com/stretchr/testify/require"
)
func TestBoxViews(t *testing.T) {
db, cleanup := newTestDB(t)
ctx := context.Background()
store := NewBoxViewsStore(db)
for _, tc := range []struct {
name string
test func(t *testing.T, ctx context.Context, store BoxViewsStore)
}{
{"BatchMergesSameKey", testBoxViewsBatchMergesSameKey},
{"AccumulatesAcrossCalls", testBoxViewsAccumulatesAcrossCalls},
{"DailyAndTotals", testBoxViewsDailyAndTotals},
{"PurgeKeepsRecent", testBoxViewsPurgeKeepsRecent},
} {
t.Run(tc.name, func(t *testing.T) {
t.Cleanup(func() {
if err := cleanup("box_views"); err != nil {
t.Fatal(err)
}
})
tc.test(t, ctx, store)
})
}
}
// 同一批里同 (user, day, visitor) 出现多次时，必须先在内存合并再写。
//
// PostgreSQL 的 ON CONFLICT DO UPDATE 不允许同一条 INSERT 两次命中同一行
// （"ON CONFLICT DO UPDATE command cannot affect row a second time"），
// 不合并的话记录器一次 flush 就会整批失败 —— 而 flush 里恰好可能包含
// 同一访客在 2 秒内刷新三次的记录。
func testBoxViewsBatchMergesSameKey(t *testing.T, ctx context.Context, store BoxViewsStore) {
now := time.Date(2026, 10, 29, 15, 4, 5, 0, time.Local)
// 同一访客三次 + 另一个访客一次，全在同一批里
err := store.RecordBatch(ctx, []RecordBoxViewOptions{
{UserID: 7, ViewedOn: now, Visitor: "aaaa"},
{UserID: 7, ViewedOn: now, Visitor: "aaaa"},
{UserID: 7, ViewedOn: now, Visitor: "aaaa"},
{UserID: 7, ViewedOn: now, Visitor: "bbbb"},
})
require.NoError(t, err)
pv, uv, err := store.Totals(ctx, 7)
require.NoError(t, err)
require.Equal(t, int64(4), pv, "三次重复访问应累加进 views")
require.Equal(t, int64(2), uv, "同一访客当天只算一个 UV")
}
func testBoxViewsAccumulatesAcrossCalls(t *testing.T, ctx context.Context, store BoxViewsStore) {
day := time.Date(2026, 10, 28, 9, 0, 0, 0, time.Local)
require.NoError(t, store.Record(ctx, RecordBoxViewOptions{UserID: 3, ViewedOn: day, Visitor: "x"}))
require.NoError(t, store.Record(ctx, RecordBoxViewOptions{UserID: 3, ViewedOn: day, Visitor: "x"}))
require.NoError(t, store.Record(ctx, RecordBoxViewOptions{UserID: 3, ViewedOn: day, Visitor: "y"}))
pv, uv, err := store.Totals(ctx, 3)
require.NoError(t, err)
require.Equal(t, int64(3), pv)
require.Equal(t, int64(2), uv)
}
func testBoxViewsDailyAndTotals(t *testing.T, ctx context.Context, store BoxViewsStore) {
base := time.Date(2026, 10, 20, 12, 0, 0, 0, time.Local)
// 20 日：2 访客共 3 次；21 日：1 访客 1 次；22 日：无记录
require.NoError(t, store.RecordBatch(ctx, []RecordBoxViewOptions{
{UserID: 11, ViewedOn: base, Visitor: "a"},
{UserID: 11, ViewedOn: base, Visitor: "a"},
{UserID: 11, ViewedOn: base, Visitor: "b"},
{UserID: 11, ViewedOn: base.AddDate(0, 0, 1), Visitor: "a"},
}))
// 另一个箱主的数据不能串进来
require.NoError(t, store.Record(ctx, RecordBoxViewOptions{
UserID: 12, ViewedOn: base, Visitor: "a",
}))
days, err := store.Daily(ctx, 11, base, base.AddDate(0, 0, 2))
require.NoError(t, err)
require.Len(t, days, 2, "没有记录的那天不返回，由上层补零")
require.Equal(t, "2026-10-20", days[0].Day.Format("2006-01-02"))
require.Equal(t, int64(3), days[0].PV)
require.Equal(t, int64(2), days[0].UV)
require.Equal(t, "2026-10-21", days[1].Day.Format("2006-01-02"))
require.Equal(t, int64(1), days[1].PV)
require.Equal(t, int64(1), days[1].UV)
pv, uv, err := store.Totals(ctx, 11)
require.NoError(t, err)
require.Equal(t, int64(4), pv)
require.Equal(t, int64(3), uv)
first, err := store.FirstDay(ctx, 11)
require.NoError(t, err)
require.Equal(t, "2026-10-20", first.Format("2006-01-02"))
}
func testBoxViewsPurgeKeepsRecent(t *testing.T, ctx context.Context, store BoxViewsStore) {
old := time.Now().AddDate(0, 0, -30)
recent := time.Now()
require.NoError(t, store.RecordBatch(ctx, []RecordBoxViewOptions{
{UserID: 5, ViewedOn: old, Visitor: "a"},
{UserID: 5, ViewedOn: recent, Visitor: "b"},
}))
n, err := store.Purge(ctx, time.Now().AddDate(0, 0, -7))
require.NoError(t, err)
require.Equal(t, int64(1), n)
pv, uv, err := store.Totals(ctx, 5)
require.NoError(t, err)
require.Equal(t, int64(1), pv, "只保留保留期内的行")
require.Equal(t, int64(1), uv)
}
internal/db/conversation.go
+3 -172
View File
@@ -6,30 +6,19 @@ package db
import (
"context"
"time"
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
"github.com/thanhpk/randstr"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"github.com/tamakyi/TamaBox/internal/dbutil"
)
var Conversations ConversationStore
var (
ErrDailyMessageLimit = errors.New("已达到每日私聊上限")
ErrConversationLimit = errors.New("会话已达到消息上限或已关闭")
)
type ConversationStore interface {
Create(ctx context.Context, opts CreateConversationOptions) (*Conversation, error)
// CreateWithFirstMessage 事务化地建会话 + 首条消息 + 消息计数。
// 单独写首条消息（用于「发第一条私聊」这类一次性动作），避免失败时留下空会话。
CreateWithFirstMessage(ctx context.Context, opts CreateConversationOptions, senderID uint, content string) (*Conversation, *Message, error)
SendMessage(ctx context.Context, opts SendConversationMessageOptions) (*Message, error)
GetByID(ctx context.Context, id uint) (*Conversation, error)
GetByToken(ctx context.Context, token string) (*Conversation, error)
GetByIDAndOwner(ctx context.Context, id, ownerID uint) (*Conversation, error)
@@ -82,39 +71,6 @@ type CreateConversationOptions struct {
MaxMessages int
}
type SendConversationMessageOptions struct {
ConversationID uint
SenderID uint
Content string
Image *CreateMessageImageOptions
}
func reserveDailyMessageTx(tx *gorm.DB, ownerID, senderID uint) error {
var sender User
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Select("id").First(&sender, senderID).Error; err != nil {
return errors.Wrap(err, "lock message sender")
}
var owner User
if err := tx.Select("daily_message_limit").First(&owner, ownerID).Error; err != nil {
return errors.Wrap(err, "get owner daily message limit")
}
if owner.DailyMessageLimit <= 0 {
return nil
}
now := time.Now()
start := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location())
var count int64
if err := tx.Table("messages").Joins("JOIN conversations ON conversations.id = messages.conversation_id").
Where("conversations.owner_id = ? AND messages.sender_id = ? AND messages.created_at >= ?", ownerID, senderID, start).
Count(&count).Error; err != nil {
return errors.Wrap(err, "count today messages")
}
if count >= int64(owner.DailyMessageLimit) {
return ErrDailyMessageLimit
}
return nil
}
func (db *conversations) Create(ctx context.Context, opts CreateConversationOptions) (*Conversation, error) {
conversation := &Conversation{
OwnerID: opts.OwnerID,
@@ -127,117 +83,6 @@ func (db *conversations) Create(ctx context.Context, opts CreateConversationOpti
return conversation, nil
}
// CreateWithFirstMessage 在一个事务里完成「建会话 + 写首条消息 + 消息计数」。
//
// 原来这三步是三次独立写入：第二步失败时会话已经提交，于是留下一条
// message_count=0、没有任何消息的「空会话」——箱主的私聊列表里能看到它，
// 点进去什么都没有；更麻烦的是 Conversations.Create 的 BeforeCreate 已经
// 生成并占用了一个 6 字符 token（唯一索引），孤儿会话会永久占着这个 token。
func (db *conversations) CreateWithFirstMessage(
ctx context.Context, opts CreateConversationOptions, senderID uint, content string,
) (*Conversation, *Message, error) {
var conv *Conversation
var msg *Message
err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if senderID == opts.AskerID {
if err := reserveDailyMessageTx(tx, opts.OwnerID, senderID); err != nil {
return err
}
}
conv = &Conversation{
OwnerID: opts.OwnerID,
AskerID: opts.AskerID,
MaxMessages: opts.MaxMessages,
}
// 走 tx 而不是 db：BeforeCreate 里生成 token 的 hook 同样会被触发。
if err := tx.Create(conv).Error; err != nil {
return errors.Wrap(err, "create conversation")
}
msg = &Message{
ConversationID: conv.ID,
SenderID: senderID,
Content: content,
}
if err := tx.Create(msg).Error; err != nil {
return errors.Wrap(err, "create first message")
}
// 原子自增，与 IncrementMessageCount 保持同一写法
if err := tx.Model(&Conversation{}).
Where("id = ?", conv.ID).
UpdateColumn("message_count", gorm.Expr("message_count + 1")).Error; err != nil {
return errors.Wrap(err, "increment message count")
}
// 私聊定量收集：新建会话即计一条（后续往来消息不重复计数）。
// 放在事务里而不是 handler 里：原来 handler 在事务之后调 IncrementQuota 且
// 失败只打 Warn，会话建成了但计数没加，箱主的「已收集」偏少、上限被绕过。
if err := incrementQuotaTx(tx, opts.OwnerID, FeatureChat, 1); err != nil {
return errors.Wrap(err, "increment chat quota")
}
return nil
})
if err != nil {
return nil, nil, err
}
return conv, msg, nil
}
func (db *conversations) SendMessage(ctx context.Context, opts SendConversationMessageOptions) (*Message, error) {
msg := &Message{ConversationID: opts.ConversationID, SenderID: opts.SenderID, Content: opts.Content}
err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
// 先锁发送者，再锁会话，保证与 CreateWithFirstMessage 的锁顺序一致，
// 避免并发下两条路径互相等待造成配额检查窗口。
var sender User
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Select("id").First(&sender, opts.SenderID).Error; err != nil {
return errors.Wrap(err, "lock message sender")
}
var conv Conversation
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&conv, opts.ConversationID).Error; err != nil {
return errors.Wrap(err, "lock conversation")
}
// 发送者必须是会话双方之一
if conv.OwnerID != opts.SenderID && conv.AskerID != opts.SenderID {
return errors.New("sender is not part of the conversation")
}
// 只有 asker 发送才消耗 owner 的每日配额
if conv.AskerID == opts.SenderID {
if err := reserveDailyMessageTx(tx, conv.OwnerID, opts.SenderID); err != nil {
return err
}
}
res := tx.Model(&Conversation{}).Where("id = ? AND message_count < max_messages AND is_closed = ?", conv.ID, false).
UpdateColumn("message_count", gorm.Expr("message_count + 1"))
if res.Error != nil {
return errors.Wrap(res.Error, "increment message count")
}
if res.RowsAffected == 0 {
return ErrConversationLimit
}
if err := tx.Create(msg).Error; err != nil {
return errors.Wrap(err, "create message")
}
if opts.Image != nil {
image := *opts.Image
image.MessageID = msg.ID
if err := tx.Create(&MessageImage{MessageID: image.MessageID, URL: image.URL, ObjectKey: image.ObjectKey, FileName: image.FileName, FileSize: image.FileSize}).Error; err != nil {
return errors.Wrap(err, "create message image")
}
}
return nil
})
if err != nil {
return nil, err
}
return msg, nil
}
func (db *conversations) GetByID(ctx context.Context, id uint) (*Conversation, error) {
var conv Conversation
if err := db.WithContext(ctx).First(&conv, id).Error; err != nil {
@@ -371,28 +216,14 @@ func (db *conversations) MarkDeletedByOwner(ctx context.Context, id uint) error
return nil
}
// 用「条件更新 + RowsAffected」代替纯 Update：
// 原来的写法是 check-then-act，双击「删除会话」或前端重复提交时，两个请求
// 都能读到 is_deleted_by_owner=false，于是都执行 UPDATE、都执行一次
// IncrementQuota(-1)。IncrementQuota 有 quota_count>0 兜底不会变负，
// 但会白吃掉本用户其他会话的计数 —— 表现为定量收集提前关闭，
// 而箱主重置计数也校准不回来。
res := db.WithContext(ctx).Model(&Conversation{}).
Where("id = ? AND is_deleted_by_owner = ?", id, false).
Update("is_deleted_by_owner", true)
if res.Error != nil {
return errors.Wrap(res.Error, "mark conversation deleted by owner")
}
if res.RowsAffected == 0 {
// 并发里被另一个请求抢先删掉了：它已经做过配额回退，这里不能再来一次。
return nil
if err := db.WithContext(ctx).Model(&Conversation{}).Where("id = ?", id).Update("is_deleted_by_owner", true).Error; err != nil {
return errors.Wrap(err, "mark conversation deleted by owner")
}
// 回退定量收集计数：删除私聊会话等价于少一条已收集内容，
// 否则达上限后即便删掉旧会话，功能仍会显示 quota_reached 关闭，须手动重置计数。
if conv.OwnerID != 0 {
// 用本 store 的 *gorm.DB 构造，避免依赖包级全局单例（详见 DeleteByID 注释）。
if err := NewFeatureControlsStore(db.DB).IncrementQuota(ctx, conv.OwnerID, FeatureChat, -1); err != nil {
if err := FeatureControls.IncrementQuota(ctx, conv.OwnerID, FeatureChat, -1); err != nil {
logrus.WithContext(ctx).WithError(err).Errorf("Failed to decrement chat quota for user %d", conv.OwnerID)
}
}
internal/db/db.go
+25 -92
View File
@@ -1,7 +1,6 @@
package db
import (
"context"
"fmt"
"time"
@@ -15,44 +14,13 @@ import (
"github.com/tamakyi/TamaBox/internal/conf"
)
// handle 保存 Init 建立的连接，供「不需要具体 store」的场景使用（如就绪探针）。
// 与下面那些业务 store 的包级变量区分开：那些是接口，这个是连接本身。
var handle *gorm.DB
// Ping 检查数据库连接是否可用。供 /readyz 就绪探针调用。
//
// 为什么需要它：原来的「探活」只能 curl /，而首页只渲染模板、不碰数据库 ——
// DB 挂了首页照样 200，反过来 Redis 挂了首页又可能 500。于是探针既会漏报也会误报。
func Ping(ctx context.Context) error {
if handle == nil {
return errors.New("database not initialized")
}
sqlDB, err := handle.DB()
if err != nil {
return errors.Wrap(err, "get sql.DB")
}
return sqlDB.PingContext(ctx)
}
var AllTables = []interface{}{
&User{}, &Question{}, &FollowUp{}, &CensorLog{}, &UploadImage{}, &UploadImageQuestion{},
&Conversation{}, &Message{}, &MessageImage{}, &UserBlock{}, &R2DeleteTask{},
&Conversation{}, &Message{}, &MessageImage{}, &UserBlock{},
// 匿名投票
&Vote{}, &VoteOption{}, &VoteFormField{}, &VoteSubmission{},
// 功能开关（提问 / 私聊 / 投票 的开关、定时、定量收集）
&FeatureControl{},
// 站方处置与举报（无管理后台，处置经 CLI 写入、运行时读表生效）
&UserRestriction{}, &ContentReport{},
// 蜜罐命中记录（审计证据，只追加不软删）
&HoneypotHit{},
// 来源 IP 的地理定位缓存（安全汇总报告用，纯 KV 缓存）
&IPGeoRecord{},
// 周期安全汇总的报告台账（period_key 唯一，保证重启不会重复发信）
&SecurityReportLog{},
// 自动封禁记录（内存态封禁的落库账本，用于事后解释与取证）
&BanRecord{},
// 箱主数据面板的访问流水（每 访客×天×箱 一行，Unscoped 语义，见 BoxView 注释）
&BoxView{},
}
func Init(typ, dsn string) (*gorm.DB, error) {
@@ -68,23 +36,27 @@ func Init(typ, dsn string) (*gorm.DB, error) {
}
db, err := gorm.Open(dialector, &gorm.Config{
Logger: newSafeLogger(),
SkipDefaultTransaction: true,
})
if err != nil {
return nil, errors.Wrap(err, "connect to database")
}
handle = db
// 配置连接池
sqlDB, err := db.DB()
if err != nil {
return nil, errors.Wrap(err, "get sql.DB from gorm")
}
// 1C1G 低配环境：调低连接池避免单连接占用过多内存。提问箱低并发，10 个打开连接绰绰有余。
// 1C1G 低配环境：调低连接池，避免每个 DB 连接占用过多内存。
// 提问箱是低并发场景，10 个打开连接绰绰有余。
// 最大打开连接数
sqlDB.SetMaxOpenConns(10)
// 最大空闲连接数
sqlDB.SetMaxIdleConns(4)
sqlDB.SetConnMaxLifetime(5 * time.Minute) // 避免长连接被数据库服务端断开
// 连接最大存活时间（避免长连接被数据库服务端断开）
sqlDB.SetConnMaxLifetime(5 * time.Minute)
// 空闲连接最大存活时间
sqlDB.SetConnMaxIdleTime(3 * time.Minute)
// 仅在明确开启迁移清理开关时处理 users 表历史重复值，避免服务启动时静默改写账号数据。
@@ -95,16 +67,26 @@ func Init(typ, dsn string) (*gorm.DB, error) {
}
}
// AutoMigrate 只负责声明式的「加表 / 加列 / 加索引」——这些变更幂等、无数据丢失风险。
if err := db.AutoMigrate(AllTables...); err != nil {
return nil, errors.Wrap(err, "auto migrate")
}
// 版本化迁移：AutoMigrate 做不了的破坏性变更（改列名/删列/改约束）与一次性数据回填
// 都收编进这里，靠 schema_migrations 账本保证「只跑一次、顺序固定、可审计」。
// 迁移失败会阻断启动 —— 半途而废的迁移比静默跳过更危险（见 runMigrations 注释）。
if err := runMigrations(db); err != nil {
return nil, errors.Wrap(err, "run versioned migrations")
// 功能开关初始化：为历史账号补齐 feature_controls 行（私聊沿用 users.allow_chat）。
// 幂等，已初始化的账号不会重复写入；失败不阻断启动，仅告警，避免依赖表抖动导致服务起不来。
if err := backfillFeatureControls(db); err != nil {
logrus.WithError(err).Warn("初始化功能开关配置时异常（可在功能管理页手动保存一次以生成配置）")
}
// 私聊开关纠偏：旧版 backfill 曾把未开启私聊的账号写为开启（GORM 零值陷阱），
// 启动期幂等复位；同样不阻断启动，失败仅告警。
if err := reconcileLegacyChatEnabled(db); err != nil {
logrus.WithError(err).Warn("私聊开关历史数据纠偏时异常（可在功能管理页手动调整私聊开关）")
}
// 私聊收集上限下线：私聊不再支持收集上限（UI 已隐藏，保存时强制清零），
// 启动期把历史残留的上限/计数一并清零，避免私聊「莫名关闭」。幂等，失败仅告警。
if err := normalizeChatQuota(db); err != nil {
logrus.WithError(err).Warn("私聊收集上限历史数据清理时异常（可在功能管理页保存一次私聊设置）")
}
// 启动期补充高频查询复合索引（幂等，适合既有库）。
@@ -118,12 +100,6 @@ func Init(typ, dsn string) (*gorm.DB, error) {
}
}
// 蜜罐表上无查询使用的索引（provider）：GORM 去掉 tag 不会自动删既有索引，
// 这里显式清理一次。失败仅告警。
if err := dropUnusedHoneypotIndexes(db); err != nil {
logrus.WithError(err).Warn("清理蜜罐表无用索引时异常（不影响服务启动）")
}
Users = NewUsersStore(db)
Questions = NewQuestionsStore(db)
FollowUps = NewFollowUpsStore(db)
@@ -132,32 +108,14 @@ func Init(typ, dsn string) (*gorm.DB, error) {
Conversations = NewConversationStore(db)
Messages = NewMessageStore(db)
MessageImages = NewMessageImageStore(db)
R2DeleteTasks = NewR2DeleteTaskStore(db)
Votes = NewVotesStore(db)
VoteOptions = NewVoteOptionsStore(db)
VoteFormFields = NewVoteFormFieldsStore(db)
VoteSubmissions = NewVoteSubmissionsStore(db)
FeatureControls = NewFeatureControlsStore(db)
Restrictions = NewRestrictionsStore(db)
Reports = NewReportsStore(db)
Honeypots = NewHoneypotStore(db)
BanRecords = NewBanRecordsStore(db)
Analytics = NewSiteAnalyticsStore(db)
BoxViews = NewBoxViewsStore(db)
BoxAnalytics = NewBoxAnalyticsStore(db)
// 旧版本把消息/密码明文存在 honeypot_hits 上；结构体已删掉这些字段，
// 但 AutoMigrate 不会删除既有列 —— 老库升级上来后历史明文仍在。
// 这里只告警不自动删：DROP COLUMN 不可逆，必须由运维确认后执行
// `TamaBox honeypot purge-creds`。
if cols, err := Honeypots.LegacyCredentialColumns(context.Background()); err == nil && len(cols) > 0 {
logrus.WithField("columns", cols).
Warn("honeypot_hits 上仍残留旧版明文凭据列，请执行 TamaBox honeypot purge-creds 清除")
}
if err := db.Use(otelgorm.NewPlugin(
otelgorm.WithDBName(conf.Database.Name),
otelgorm.WithoutQueryVariables(),
)); err != nil {
return nil, errors.Wrap(err, "register otelgorm plugin")
}
@@ -236,13 +194,7 @@ func dedupeUniqueFields(db *gorm.DB) error {
func ensureFrequentlyUsedIndexes(db *gorm.DB) error {
indexes := []string{
`CREATE INDEX IF NOT EXISTS idx_questions_asker_user_id ON questions(asker_user_id)`,
// 全站数据页（/stats）：按 created_at 做范围扫描后按天/小时分组。
// 没有这个索引时，趋势与热力图会退化成全表扫描 + 排序；加上之后是范围扫描 + 聚合。
`CREATE INDEX IF NOT EXISTS idx_questions_created_at ON questions(created_at)`,
`CREATE INDEX IF NOT EXISTS idx_questions_user_private_created ON questions(user_id, is_private, created_at)`,
// 「下一条未读」：user_id + is_read 过滤后按 created_at 取最早一条。
// 上面那条中间隔着 is_private，帮不上这个排序。
`CREATE INDEX IF NOT EXISTS idx_questions_user_unread_created ON questions(user_id, is_read, created_at)`,
`CREATE INDEX IF NOT EXISTS idx_users_show_in_home_created ON users(show_in_home, created_at)`,
`CREATE INDEX IF NOT EXISTS idx_votes_status_visibility_created ON votes(status, visibility, created_at)`,
`CREATE INDEX IF NOT EXISTS idx_messages_sender_created ON messages(sender_id, created_at)`,
@@ -256,25 +208,6 @@ func ensureFrequentlyUsedIndexes(db *gorm.DB) error {
return nil
}
// dropUnusedHoneypotIndexes 删除蜜罐表上没有任何查询使用的索引。
//
// 背景：provider 字段原先带 gorm:"index"，但全代码库没有一处按 provider
// 过滤或排序（TopSources 用 max(provider) 随 group by 顺带取，不需要独立索引）。
// 实测该索引占 10 万行约 648 kB，对一张「只增不减」的审计表是纯粹的空间浪费
// 与写放大。去掉 GORM tag 只影响新建库，既有库上的旧索引要显式 DROP。
//
// 幂等：索引不存在时不报错。失败仅告警，不阻断启动。
func dropUnusedHoneypotIndexes(db *gorm.DB) error {
// GORM 生成的索引名规则：idx_<表名>_<列名>。
if db.Migrator().HasIndex(&HoneypotHit{}, "idx_honeypot_hits_provider") {
if err := db.Migrator().DropIndex(&HoneypotHit{}, "idx_honeypot_hits_provider"); err != nil {
return errors.Wrap(err, "drop unused honeypot index")
}
logrus.Info("已删除蜜罐表上无查询使用的 provider 索引")
}
return nil
}
func fixPostgresSequences(db *gorm.DB) error {
// 使用配置的 schema（未配置时回退 public），避免硬编码 nekobox。
schema := conf.Database.Schema
internal/db/feature_control.go
+55 -85
View File
@@ -20,8 +20,6 @@ import (
var FeatureControls FeatureControlsStore
var ErrFeatureQuotaReached = errors.New("功能收集配额已满")
var _ FeatureControlsStore = (*featureControls)(nil)
// 受控功能标识（feature_controls.feature 取值）。
@@ -68,23 +66,29 @@ type featureControls struct {
*gorm.DB
}
// FeatureControl 单个功能（提问 / 私聊 / 投票）的开关、定时与定量收集配置。
// Enabled 为手动总开关；OpenAt / CloseAt 为一次性定时（nil 表示不限该侧）；
// QuotaLimit / QuotaCount 为定量收集（0 表示不限制）。最终状态由 Evaluate 综合计算。
// FeatureControl 提问箱单个功能（提问 / 私聊 / 投票）的开关、定时与定量收集配置。
//
// 计数不做定时重置：一轮结束后由箱主手动「重置计数」，避免与定时开关叠加产生
// 难以预期的自动恢复行为。
// 三类控制互不覆盖，最终可用状态由 Evaluate 综合计算：
// - Enabled：手动总开关；
// - OpenAt / CloseAt：定时开放与定时关闭（nil 表示不限制该侧）；
// - QuotaLimit / QuotaCount：定量收集，累计收集数达到上限后自动关闭（0 表示不限制）。
//
// 计数不做定时重置：一轮收集结束后由箱主在功能管理页手动「重置计数」开启下一轮，
// 避免与定时开关叠加产生难以预期的自动恢复行为。
type FeatureControl struct {
dbutil.Model
UserID uint `gorm:"uniqueIndex:idx_feature_control_user_feature;not null" json:"-"`
Feature string `gorm:"size:20;uniqueIndex:idx_feature_control_user_feature;not null" json:"feature"`
// ⚠️ 不要给 Enabled 加 gorm:"default:true"：GORM 在 Create 时会把零值 false 替换为
// 默认值 true，导致「取消勾选保存」后库里仍是 true、复选框自动恢复勾选。
Enabled bool `json:"enabled"`
// ⚠️ 不要给 Enabled 加 gorm:"default:true" 标签：
// GORM 在 Create 时会把零值 false 替换为字段默认值（true），导致「取消勾选保存」后
// 数据库里仍是 true、复选框自动恢复为勾选。去掉标签后 GORM 会原样写入显式设置的值。
Enabled bool `json:"enabled"`
// OpenAt / CloseAt：一次性定时开放 / 关闭（nil 表示不限制该侧）。
OpenAt *time.Time `json:"open_at"`
CloseAt *time.Time `json:"close_at"`
// 循环定时（每周）：ScheduleDays 为逗号分隔的周几（0=周日…6=周六），空表示每天都开放；
// ScheduleStart/ScheduleEnd 为每日时间段 "HH:MM"（留空表示全天）。两者皆空即未启用。
// 循环定时（每周循环）：ScheduleDays 为逗号分隔的周几（0=周日…6=周六，与 time.Weekday 一致），
// 空表示每天都开放；ScheduleStart/ScheduleEnd 为每日时间段 "HH:MM"（留空表示该日全天）。
// 两者都为空时表示未启用循环定时。
ScheduleDays string `gorm:"size:31" json:"schedule_days"`
ScheduleStart string `gorm:"size:5" json:"schedule_start"`
ScheduleEnd string `gorm:"size:5" json:"schedule_end"`
@@ -174,8 +178,8 @@ func (fc *FeatureControl) scheduleDayOpen(day time.Time) bool {
return fc.ScheduleDays == "" || containsWeekday(fc.ScheduleDays, int(day.Weekday()))
}
// scheduleWindow 返回单日开放窗口的分钟数 [startM, endM)。未设置时间段时视为全天；
// 配置非法时返回错误（调用方按「不限制」处理）。
// scheduleWindow 返回单日开放窗口的分钟数 [startM, endM)。
// 未设置时间段时视为全天 [0, 1440)。配置非法时返回错误（调用方按"不限制"处理）。
func (fc *FeatureControl) scheduleWindow() (startM, endM int, err error) {
if fc.ScheduleStart == "" && fc.ScheduleEnd == "" {
return 0, 24 * 60, nil
@@ -338,8 +342,9 @@ func startOfDay(t time.Time) time.Time {
return time.Date(y, m, d, 0, 0, 0, 0, t.Location())
}
// DefaultFeatureControl 返回某功能的默认配置（尚未落库时的行为）。提问与投票默认开启
// （与历史行为一致）；私聊默认关闭，沿用 users.allow_chat 默认值，避免历史账号被动开启。
// DefaultFeatureControl 返回某功能的默认配置（尚未落库时的行为）。
// 提问与投票默认开启（与历史行为一致）；私聊默认关闭，沿用 users.allow_chat 的默认值，
// 避免历史账号在功能上线后被动开启私聊。
func DefaultFeatureControl(userID uint, feature string) *FeatureControl {
return &FeatureControl{
UserID: userID,
@@ -348,8 +353,8 @@ func DefaultFeatureControl(userID uint, feature string) *FeatureControl {
}
}
// FeatureStateOf 读取某用户某功能当前的综合状态。查询失败或无存储时回退默认配置，
// 保证单个依赖表异常不会让整站功能不可用。
// FeatureStateOf 便捷入口：读取某用户某功能在当前的综合状态。
// 查询失败或无存储时回退到默认配置，保证单个依赖表异常不会让整站功能不可用。
func FeatureStateOf(ctx context.Context, userID uint, feature string) FeatureState {
if FeatureControls == nil {
return DefaultFeatureControl(userID, feature).Evaluate(time.Now())
@@ -362,26 +367,6 @@ func FeatureStateOf(ctx context.Context, userID uint, feature string) FeatureSta
return fc.Evaluate(time.Now())
}
// FeatureStateOfStrict 与 FeatureStateOf 相同，但查询失败时返回错误而不回退默认配置。
//
// 给**写入路径**用。FeatureStateOf 的 fail-open 对读展示是对的（配置表抖动不该让
// 页面白屏），但对写入是危险的：它回退到 DefaultFeatureControl —— 提问与投票的
// 默认值是「开启」，于是箱主明明设了「已关闭」或「已达上限」，只要这次读配置失败
// 就被放行，等于定量收集与功能开关都能被一次数据库抖动绕过去。
// 与审核链路「不可用即拒绝」同一口径。
func FeatureStateOfStrict(ctx context.Context, userID uint, feature string) (FeatureState, error) {
if FeatureControls == nil {
// 未装配（测试 / 部分初始化）：沿用默认配置，否则所有写路径都会失败。
return DefaultFeatureControl(userID, feature).Evaluate(time.Now()), nil
}
fc, err := FeatureControls.Get(ctx, userID, feature)
if err != nil {
logrus.WithContext(ctx).WithError(err).Errorf("Failed to get feature control %q of user %d", feature, userID)
return FeatureState{}, errors.Wrap(err, "get feature control")
}
return fc.Evaluate(time.Now()), nil
}
// FeatureOpen 便捷入口：某用户某功能当前是否可用。
func FeatureOpen(ctx context.Context, userID uint, feature string) bool {
return FeatureStateOf(ctx, userID, feature).Open
@@ -448,7 +433,7 @@ type UpdateFeatureControlOptions struct {
QuotaLimit int64
}
// Save 写入功能配置。用 ON CONFLICT 幂等写入并显式列出更新列，
// Save 写入功能配置。使用 ON CONFLICT 幂等写入，并显式列出更新列，
// 避免把 quota_count（已收集数量）误重置为 0。
func (db *featureControls) Save(ctx context.Context, userID uint, feature string, opts UpdateFeatureControlOptions) error {
now := time.Now()
@@ -509,37 +494,11 @@ func (db *featureControls) ResetQuota(ctx context.Context, userID uint, feature
// IncrementQuota 累加收集计数（delta 可为负，用于删除内容时回退计数）。
// 负 delta 不会把计数减到 0 以下（WHERE quota_count > 0），避免误删历史内容导致负计数。
func (db *featureControls) IncrementQuota(ctx context.Context, userID uint, feature string, delta int64) error {
return incrementQuotaTx(db.WithContext(ctx), userID, feature, delta)
}
// incrementQuotaTx 是配额递增的唯一实现，接受任意 *gorm.DB（可以是事务）。
//
// 为什么要暴露一个「能用事务」的版本：配额与内容必须是同生共死的关系。
// 原来「创建提问」与「quota_count+1」是两次独立写入，后者失败只打一条 Warn ——
// 于是计数比真实行数少，箱主的「已收集 7/10」永远偏低，达到上限后仍能继续收，
// 而重置计数也校准不回来（重置是把计数清零，与实际行数更脱节）。
// 现在内容 store 把这一步放进自己的事务里，任一步失败整体回滚，计数天然对齐。
func reserveFeatureQuotaTx(tx *gorm.DB, userID uint, feature string) error {
if err := tx.Clauses(clause.OnConflict{DoNothing: true}).Create(DefaultFeatureControl(userID, feature)).Error; err != nil {
return errors.Wrap(err, "initialize feature quota")
}
var fc FeatureControl
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
Where("user_id = ? AND feature = ?", userID, feature).First(&fc).Error; err != nil {
return errors.Wrap(err, "lock feature quota")
}
if fc.QuotaLimit > 0 && fc.QuotaCount >= fc.QuotaLimit {
return ErrFeatureQuotaReached
}
return nil
}
func incrementQuotaTx(tx *gorm.DB, userID uint, feature string, delta int64) error {
if delta == 0 {
return nil
}
now := time.Now()
q := tx.Model(&FeatureControl{}).
q := db.WithContext(ctx).Model(&FeatureControl{}).
Where("user_id = ? AND feature = ?", userID, feature)
if delta < 0 {
q = q.Where("quota_count > 0")
@@ -561,7 +520,7 @@ func incrementQuotaTx(tx *gorm.DB, userID uint, feature string, delta int64) err
fc.QuotaCount = delta
}
fc.QuotaResetAt = &now
created := tx.
created := db.WithContext(ctx).
Clauses(clause.OnConflict{DoNothing: true}).
Create(fc)
if created.Error != nil {
@@ -571,7 +530,7 @@ func incrementQuotaTx(tx *gorm.DB, userID uint, feature string, delta int64) err
return nil
}
// 并发下配置行可能刚被其它请求创建：补一次累加，保证计数不丢。
retry := tx.Model(&FeatureControl{}).
retry := db.WithContext(ctx).Model(&FeatureControl{}).
Where("user_id = ? AND feature = ?", userID, feature).
Updates(map[string]interface{}{
"quota_count": gorm.Expr("quota_count + ?", delta),
@@ -585,12 +544,13 @@ func incrementQuotaTx(tx *gorm.DB, userID uint, feature string, delta int64) err
// backfillFeatureControls 为尚未初始化的历史账号补齐功能配置行。
//
// 私聊开关此前落在 users.allow_chat，提问/投票一直默认开启；功能上线后没有配置行时
// Get 会回退默认值（私聊默认关闭），导致已开启私聊的历史账号被静默关闭，
// 故在 AutoMigrate 之后按 users.allow_chat 回填私聊，其余按「开启」回填。
// 背景：私聊开关此前落在 users.allow_chat，提问/投票则一直默认开启。功能上线后若没有
// 对应的配置行，Get 会回退到默认值（私聊默认关闭），导致已开启私聊的历史账号被静默关闭。
// 因此在 AutoMigrate 之后按 users.allow_chat 回填私聊开关，其余功能按"开启"回填。
//
// 幂等：每轮只挑仍缺行的账号，分批 + ON CONFLICT DO NOTHING，避免不同数据库上
// 「边插入边查同一张表」的差异行为，也保证多实例并发启动时不重复插入。
// 幂等：每轮只挑出仍缺配置行的账号，写完后进入下一轮，直到没有遗漏。
// 分批 + ON CONFLICT DO NOTHING，避免"边插入边查同一张表"在不同数据库上的差异行为，
// 并保证并发启动（多实例同时启动）时不会重复插入。
func backfillFeatureControls(db *gorm.DB) error {
// backfillBatchSize 每轮处理的账号数，控制单次事务体积与内存占用。
const backfillBatchSize = 500
@@ -656,20 +616,28 @@ func backfillFeatureControls(db *gorm.DB) error {
// reconcileLegacyChatEnabled 修复旧版 backfill 写入的私聊错误开关。
//
// 背景：早期 Enabled 带 gorm:"default:true"，backfill 为 allow_chat=false 的用户补行时
// false 被替换为 true，私聊被被动开启；UpdateChatSettings 还会把 allow_chat 同步为 true。
// 背景：早期版本 FeatureControl.Enabled 带 gorm:"default:true" 标签，backfill 为
// allow_chat=false 的用户补私聊行时，false 被 GORM 替换为默认值 true，导致私聊被被动开启；
// 且 UpdateChatSettings 会把 users.allow_chat 反向同步为 true，形成持久化。
//
// 纠偏条件（必须同时满足，只命中「纯 backfill 默认行」，绝不碰箱主配置过的行）：
// feature='chat' 且 enabled=true；对应 users.allow_chat=false；该行无任何自定义配置
// （open_at/close_at 为空、quota_limit=0、循环定时为空）；updated_at <= created_at。
// 满足即复位 enabled=false 并同步 users.allow_chat=false。幂等，已配置行不会重复命中。
// 纠偏条件（必须同时满足，只命中"纯 backfill 默认行"，绝不碰箱主配置过的行）：
// - feature = 'chat' 且 enabled = true；
// - 对应 users.allow_chat = false（箱主从未在面板开启私聊——面板开启会同步 allow_chat=true）；
// - 该行无任何自定义配置（open_at / close_at 为空、quota_limit = 0、循环定时为空）；
// - updated_at <= created_at（从未被面板保存过，updated_at 未变化）。
//
// 满足条件即复位 feature_controls.enabled = false，并同步 users.allow_chat = false。
// 幂等：每轮只处理仍满足条件的行，直到没有遗漏；已复位/已配置的行不会重复命中。
func reconcileLegacyChatEnabled(db *gorm.DB) error {
// reconcileBatchSize 每轮处理的账号数，控制单次事务体积。
const reconcileBatchSize = 500
// 两者只匹配纯默认配置的私聊行（无一次性窗口/循环定时/定量上限），仅列前缀不同：
// FC 版带 "fc." 用于 SELECT；纯版不带前缀用于 UPDATE（GORM 不会为 UPDATE 自动加别名，
// 带前缀会报 missing FROM-clause entry for table "fc"）。同时兼容旧行 NULL 与新行空串。
// pureDefaultFilterFC / pureDefaultFilterPlain 只匹配纯默认配置的私聊行
// （无一次性窗口/循环定时/定量上限）。两者仅列前缀不同：
// - FC 版带 "fc." 前缀，用于 SELECT（feature_controls fc 别名场景）；
// - 纯版不带前缀，用于 UPDATE（GORM 不会为 UPDATE 自动加别名，带前缀会报
// missing FROM-clause entry for table "fc"）。
// 同时兼容旧行 schedule 列为 NULL 与新行空串两种情况。
pureDefaultFilterFC := "fc.open_at IS NULL AND fc.close_at IS NULL AND fc.quota_limit = 0" +
" AND (fc.schedule_days IS NULL OR fc.schedule_days = '')" +
" AND (fc.schedule_start IS NULL OR fc.schedule_start = '')" +
@@ -735,9 +703,11 @@ func reconcileLegacyChatEnabled(db *gorm.DB) error {
}
// normalizeChatQuota 清零私聊行上历史残留的收集上限与计数。
// 私聊不提供收集上限（会话是双向对话，限制「新建会话数」意义不大），UI 已隐藏该字段、
// 保存时强制清零；此处在启动期兜底清零，避免达到残留上限后私聊「莫名关闭」。
// 幂等，失败由调用方告警（不阻断启动）。
//
// 背景：私聊不提供收集上限能力（会话是双向对话，限制「新建会话数」意义不大），
// UI 已隐藏该字段、保存时强制清零；此处在启动期做一次性兜底，把旧版本
// 设置过的私聊上限/计数统一清零，避免达到残留上限后私聊「莫名关闭」。
// 幂等：重复执行不产生任何变更，失败由调用方告警（不阻断启动）。
func normalizeChatQuota(db *gorm.DB) error {
res := db.Model(&FeatureControl{}).
Where("feature = ? AND (quota_limit > 0 OR quota_count > 0)", FeatureChat).
internal/db/follow_ups.go
+38 -66
View File
@@ -11,42 +11,42 @@ import (
)
// MaxFollowUpCount 每条提问允许的最大追问次数（防滥用）。
// 提问者被回答后，用 token（或登录账号）继续追问，达到上限后不可再追问。
const MaxFollowUpCount = 3
// 追问相关错误，供 handler 区分处理，避免把业务错误当 500。
// 追问相关错误（供 handler 区分处理，避免把业务错误当 500）
var (
ErrFollowUpLimitReached = errors.New("follow up limit reached")
ErrFollowUpNotFound = errors.New("follow up not found")
// ErrFollowUpLimitReached 追问次数已达上限
ErrFollowUpLimitReached = errors.New("follow up limit reached")
// ErrFollowUpNotFound 追问不存在或不属于该问题
ErrFollowUpNotFound = errors.New("follow up not found")
// ErrFollowUpAlreadyAnswered 追问已被回答（禁止覆盖）
ErrFollowUpAlreadyAnswered = errors.New("follow up already answered")
// ErrFollowUpAwaitingReply 上一条追问尚未被箱主回复，不允许继续追问。
// 由 CreateIfBelowLimit 在事务内判定（见该方法的注释）。
ErrFollowUpAwaitingReply = errors.New("previous follow up awaiting reply")
)
var FollowUps FollowUpsStore
type FollowUpsStore interface {
// CreateIfBelowLimit 原子创建追问：仅当该问题追问次数未达上限时创建；
// 事务内锁定问题行串行化并发追问，消除 count-then-create 竞态。已达上限返回 (false, ErrFollowUpLimitReached)。
// CreateIfBelowLimit 原子创建追问：仅当该问题追问次数未达上限时创建。
// 返回 created=false 且 err==ErrFollowUpLimitReached 表示已达上限。
// 通过事务内锁定问题行，串行化同一问题的并发追问，消除 count-then-create 竞态。
CreateIfBelowLimit(ctx context.Context, opts CreateFollowUpOptions) (created bool, err error)
GetByQuestionID(ctx context.Context, questionID uint) ([]*FollowUp, error)
// GetLatestByQuestionID 返回某条提问最新的一条追问；无追问时返回 (nil, nil)。
GetLatestByQuestionID(ctx context.Context, questionID uint) (*FollowUp, error)
// GetByQuestionIDs 批量获取多个提问的追问，按 question_id 分组返回（导出场景合并 N+1 为 1 次 IN 查询）。
// GetByQuestionIDs 批量获取多个提问的追问，按 question_id 分组返回。
// 用于账号导出等场景，将 N 次单题查询合并为 1 次 IN 查询，避免 N+1。
GetByQuestionIDs(ctx context.Context, questionIDs []uint) (map[uint][]*FollowUp, error)
CountByQuestionID(ctx context.Context, questionID uint) (int64, error)
// AnswerByID 回答某条追问；questionID 防越权（必须属于该问题），仅允许回答尚未回答的（answer 为空）。
// 已回答返回 ErrFollowUpAlreadyAnswered，不存在/不属于该问题返回 ErrFollowUpNotFound。
AnswerByID(ctx context.Context, questionID uint, id uint, answer string) error
// UpdateAnswerByID 修改某条追问的回答内容（带 question_id 条件防越权），
// 允许覆盖已回答的（供主人修改回复）；返回 wasFirst 表示这是首次回答（此前为空）。
// AnswerByID 回答某条追问；questionID 用于防止越权（必须属于该问题）。
// 仅允许回答尚未回答的追问（answer 为空），已回答的返回 ErrFollowUpAlreadyAnswered，
// 不存在/不属于该问题返回 ErrFollowUpNotFound。
UpdateAnswerByID(ctx context.Context, questionID uint, id uint, answer string) (wasFirst bool, err error)
// DeleteByQuestionID 删除某条提问时级联清理其全部追问。
//
// 用 Unscoped 真删：追问正文是提问者的个人内容，随提问一并真删（与 questions.DeleteByID
// 对主表的真删口径一致）。软删会留下带 deleted_at 的追问文本，且这些孤儿行的
// question_id 指向一个已不存在的提问 —— 与「删除即真删、个人数据不残留」的意图相悖。
AnswerByID(ctx context.Context, questionID uint, id uint, answer string) error
// UpdateAnswerByID 修改某条追问的回答内容（带 question_id 条件防止越权），
// 与 AnswerByID 不同，此处允许覆盖已回答的追问（供主人修改回复使用）。
// 不存在/不属于该问题返回 ErrFollowUpNotFound。
UpdateAnswerByID(ctx context.Context, questionID uint, id uint, answer string) error
// DeleteByQuestionID 删除某条提问时级联清理其全部追问（软删除，与提问保持一致）。
DeleteByQuestionID(ctx context.Context, questionID uint) error
}
@@ -92,23 +92,6 @@ func (db *followUps) CreateIfBelowLimit(ctx context.Context, opts CreateFollowUp
return ErrFollowUpLimitReached
}
// 「上一条追问必须先被回复」也必须在事务内判断。
//
// 这段校验原来只在 handler 里做（事务外）：双击提交时两个请求都读到
// 「最新一条还没回复」，随后被这行 FOR UPDATE 串行化，各自 count 都 < 3，
// 于是两条内容相同的追问都创建成功 —— 吃掉 2/3 名额，箱主还会收两封邮件。
// 行锁只保护「条数」，不保护「业务前置条件」，所以判断必须挪进来。
var latest FollowUp
if err := tx.Where("question_id = ?", opts.QuestionID).
Order("id DESC"). // 用 id 而非 created_at：同毫秒写入时时间排序不稳定
Limit(1).
Find(&latest).Error; err != nil {
return errors.Wrap(err, "get latest follow up for reply check")
}
if latest.ID != 0 && latest.Answer == "" {
return ErrFollowUpAwaitingReply
}
f := &FollowUp{
QuestionID: opts.QuestionID,
Content: opts.Content,
@@ -137,7 +120,8 @@ func (db *followUps) GetByQuestionID(ctx context.Context, questionID uint) ([]*F
return followUps, nil
}
// GetLatestByQuestionID 返回某条提问最新的一条追问（created_at 倒序）；无追问时返回 (nil, nil)，供发布前校验上一条是否已回复。
// GetLatestByQuestionID 返回某条提问最新的一条追问（created_at 倒序取首条）；
// 无追问时返回 (nil, nil)。供发布追问前校验"上一条是否已回复"。
func (db *followUps) GetLatestByQuestionID(ctx context.Context, questionID uint) (*FollowUp, error) {
var fu FollowUp
err := db.WithContext(ctx).
@@ -185,8 +169,9 @@ func (db *followUps) CountByQuestionID(ctx context.Context, questionID uint) (in
return count, nil
}
// AnswerByID 更新回答（带 question_id 防越权）。
// 原子条件含 answer=”，已回答的不被覆盖；RowsAffected==0 再查一次以区分"不存在"与"已回答"。
// AnswerByID 更新某条追问的回答内容（带 question_id 条件防止越权）。
// 原子更新条件含 answer=”：已回答的追问不会被覆盖（避免重复提交时邮件/回答被二次写入）。
// RowsAffected==0 时再查一次以区分"不存在"与"已回答"，返回对应错误。
func (db *followUps) AnswerByID(ctx context.Context, questionID uint, id uint, answer string) error {
res := db.WithContext(ctx).
Model(&FollowUp{}).
@@ -213,36 +198,23 @@ func (db *followUps) AnswerByID(ctx context.Context, questionID uint, id uint, a
// UpdateAnswerByID 修改某条追问的回答内容（带 question_id 条件防止越权），
// 允许覆盖已回答的追问（用于主人修改回复）。不存在/不属于该问题返回 ErrFollowUpNotFound。
func (db *followUps) UpdateAnswerByID(ctx context.Context, questionID uint, id uint, answer string) (bool, error) {
var wasFirst bool
err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
// 先读旧值判断「是否首次回答」。handler 里拿不到可靠旧值：
// 它手上的 question 是请求开始时读的，并发下可能已经过期。
var fu FollowUp
if err := tx.Where("id = ? AND question_id = ?", id, questionID).First(&fu).Error; err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return ErrFollowUpNotFound
}
return errors.Wrap(err, "get follow up")
}
wasFirst = fu.Answer == ""
if err := tx.Model(&FollowUp{}).
Where("id = ? AND question_id = ?", id, questionID).
Update("answer", answer).Error; err != nil {
return errors.Wrap(err, "update follow up answer")
}
return nil
})
if err != nil {
return false, err
func (db *followUps) UpdateAnswerByID(ctx context.Context, questionID uint, id uint, answer string) error {
res := db.WithContext(ctx).
Model(&FollowUp{}).
Where("id = ? AND question_id = ?", id, questionID).
Update("answer", answer)
if res.Error != nil {
return errors.Wrap(res.Error, "update follow up answer")
}
return wasFirst, nil
if res.RowsAffected == 0 {
return ErrFollowUpNotFound
}
return nil
}
// DeleteByQuestionID 删除某条提问时级联清理其全部追问（真删，与提问保持一致）。
// DeleteByQuestionID 删除某条提问时级联清理其全部追问（软删除，与提问保持一致）。
func (db *followUps) DeleteByQuestionID(ctx context.Context, questionID uint) error {
if err := db.WithContext(ctx).Unscoped().Where("question_id = ?", questionID).Delete(&FollowUp{}).Error; err != nil {
if err := db.WithContext(ctx).Where("question_id = ?", questionID).Delete(&FollowUp{}).Error; err != nil {
return errors.Wrap(err, "delete follow ups by question id")
}
return nil

Some files were not shown because too many files have changed in this diff Show More