announcement v1

.workbuddy/memory/2026-10-22.md

@@ -36,6 +36,124 @@
   位图唯一的理由是素材要给非 CSS 场景复用。文档与 INSTALL.txt 都已改。
 - `image_bucket_cdn_host` 沿用 app.ini 同名键（只写主机名），`export_assets.py` 据此拼公开地址。
 
+## 线上 521 排障（box.shiroko.one 打不开）
+
+- 现象：`https://box.shiroko.one` 全路径 **521**，同机 IP+端口正常。
+- 实测链路：`box.shiroko.one` → CNAME `cloudflare.182682.xyz`（第三方 CF SaaS 接入/优选，
+  上游 `source.cfnode.eu.org`），**不是** `<UUID>.cfargotunnel.com`。DNS/TLS 均正常（tls=0），
+  响应体 `error code: 521`，5 次请求全 LAX，0.6s 快速失败（RST 特征，非超时）。
+- 对照实验有价值：`box.tama.guru` 走**同一个** CNAME 目标却正常 301 → 中转 zone 边缘健康；
+  它不回源，而 box.shiroko.one 要回源才 521 ⇒ 断点在「CF → 源站」这一段。
+- `shiroko.one` / `www` / `tama.guru` apex 都 CNAME `navi-ew2.pages.dev`（CF Pages 导航站），与本站无关，
+  别拿它们的 200 当证据。
+- 候选根因（待服务器侧确认）：① cloudflared 断开（严格说 tunnel 无 connector 多为 502/1033）；
+  ② `scripts/edgeone-origin-whitelist.sh` 的 `REJECT tcp-reset` 拦掉 CF 直连回源——脚本注释里
+  「521」本就是白名单漏放的既有症状；③ 回源 IP 过期（服务器 IP 变动 / 第三方面板未更新）。
+- 注意矛盾点：用户本地能连 IP+端口 ⇒ 白名单大概率没生效或不覆盖该端口 ⇒ 更偏向 ③/tunnel 侧。
+
+**根因已确认（服务器实测）**
+- `systemctl is-active cloudflared` = **inactive**，`pgrep` 无进程 → Tunnel 断。
+  journald 最后一条 2026-10-21T21:42:22Z（CST 10-22 05:42），此后无日志 ⇒ **停了约 7 小时**。
+- 死前日志模式：`accept stream listener encountered a failure while serving` +
+  `failed to accept QUIC stream: timeout: no recent network activity` + `datagram handler
+  error="context canceled"` + `Retrying connection in up to 1s`，connIndex 2/3 反复 →
+  UDP 7844 QUIC 长时间不稳（美西 23.94.211.138）。**inactive 而非 failed ⇒ 是被正常 stop 的，
+  不是崩溃**，与用户「昨晚升级 nginx 到 1.30.x」的时间点吻合（升级流程连带停服）。
+- 应用侧全好：`*:5877` 监听（tamabox pid），loopback 200。
+- `iptables -S INPUT` 只有 `-i eth0 --dport 8118/5877 -j DROP`，**EO_IN / ipset EO_ORIGIN 都不存在**
+  ⇒ EdgeOne 白名单脚本当前未生效。且 DROP 限定 `-i eth0`，网卡名若不叫 eth0 则规则空转。
+- 关键推论：CF 一定走 tunnel 而非直连 5877（否则 DROP 空转应 200 而非 521）⇒ 521 完全由 tunnel 断解释。
+
+**续：start 之后仍 521**
+- 用户确认：**5877 只允许 Tailscale（100.84.113.84:5877）访问**，公网靠 iptables DROP 封掉。
+  ⇒ 排除「CF 直连公网 5877」这条路径，CF 只能经 tunnel 回源。
+- `systemctl start cloudflared` → `active`，`sleep 5` 后 curl 域名仍 **521**。
+- 待分辨：① connector 尚未完成边缘注册（sleep 5 偏短）；② 本机 tunnel 与 CF/SaaS 侧
+  `box.shiroko.one` 绑定的 origin（应为 `<uuid>.cfargotunnel.com`）不是同一个；
+  ③ 该 hostname 的 Public Hostname / ingress 未指向 `http://127.0.0.1:5877`。
+- 决定性隔离实验：临时 quick tunnel（`cloudflared tunnel --url http://127.0.0.1:5877`）
+  拿 trycloudflare 域名直测 —— 200 则应用+出站正常，问题在 CF 侧绑定。
+
+**journald 取证（关键）**
+- `protocol=quic`，`location=la01`。从 10-21 13:53:30 起就是死循环：
+  `INF Registered tunnel connection` → 约 3s 后 `ERR failed to accept QUIC stream:
+  timeout: no recent network activity` + `datagram handler error="context canceled"` +
+  `WRN failed to serve tunnel connection error="accept stream listener encountered a failure
+  while serving"` → `INF Retrying connection in up to 1s` → 再注册。connIndex 0/1/2 全部如此，
+  每 ~3 分钟一轮，一直持续到 10-21 21:42:40。
+- ⇒ **UDP 7844 的 QUIC 在这台机器上基本不可用**（RackNerd 美西 → CF la01），这是历史顽疾，
+  不是本次新故障。根治手段 = `TUNNEL_TRANSPORT_PROTOCOL=http2`（走 TCP 443）。
+- 🔴 但 12:56 `systemctl start` 之后 journal 里**一条新日志都没有**（最后仍是 10-21 21:42:40，
+  PID 626）⇒ 新进程疑似启动即退出/token 无效，`is-active=active` 可能是重启窗口里的瞬时值。
+  需 `systemctl status` 看 Restart 计数与 ExecMainStatus。
+- 旁证：EdgeOne 那条备用通道同样不通（18080 无监听、EO_IN/ipset 均不存在）。
+
+**结论定案**
+- 重大纠正：cloudflared **从未死过**。`systemctl status` 显示 `active (running) since 2026-10-20 05:32:44`，
+  Main PID 626 存活 2 天+。前面「21:42 后无日志」不是进程退出，而是 QUIC 连接最后注册成功后没再报错
+  （只有 24h 一次的版本提醒）。所以「tunnel 断导致 521」这个假设是错的。
+- 改 `TUNNEL_TRANSPORT_PROTOCOL=http2` 后：4 个 connector 全部 `Registered tunnel connection
+  ... protocol=http2`，`SUMMARY: Environment is healthy. Cloudflared will use 'http2' as primary
+  protocol`，零错误 ⇒ **tunnel 侧完全健康**。QUIC 抖动问题也顺手解决了（该 drop-in 值得长期保留）。
+- 但站点仍 521 ⇒ **问题 100% 在 CF 侧 origin/路由，与本机 tunnel 无关**。
+- 公网实测 `23.94.211.138`：5877 / 18080 / 80 / 443 **全部 timeout**（不止 5877）。
+  ⇒ 若第三方 SaaS 的 origin 填的是「公网 IP:5877」，CF 同样连不上 → 521。
+  这解释了「突然」：用户近期把 5877 收敛为仅 Tailscale（100.84.113.84）可达。
+- 本机 tunnel 身份（从 token 解出，注意 token 已明文暴露需轮换）：
+  tunnel id `ba34e35d-e517-498a-b2cd-7275c22e354e`，account tag `0c99c40b475a65b393abaca3ca91731b`。
+- 修复方向：①（推荐）第三方面板把 origin 改成 `ba34e35d-...cfargotunnel.com`，并在
+  Zero Trust → Tunnels → 该 tunnel 的 Public Hostnames 补 `box.shiroko.one → http://127.0.0.1:5877`；
+  ②（不推荐）放行 CF 回源网段到 5877，等于重新暴露源站。
+- ⚠️ 安全 P0：tunnel token 在对话截图里明文出现，等同凭据泄露 → 必须 Refresh token 后重装服务。
+
+**真凶：SaaS origin 指向被封的公网**
+- SaaS 自定义主机名 `box.shiroko.one` 的「源服务器」= `box-direct.337845818.best`。
+- 实测该 origin 域名 **解析到 Cloudflare 自己的 IP**（104.21.47.52 / 172.67.144.141，
+  `Server: cloudflare`，CF-RAY）⇒ 它是**橙云（proxied）记录**，不是灰云 A 记录。
+  `http://` 301（Always Use HTTPS）、`https://` **521** —— 它自己也回源失败。
+- 源站 `23.94.211.138`（colocrossing，RackNerd 上游）：22 / 80 / 443 / 5877 / 18080
+  **全部 timeout**。不只应用端口，连 SSH 都不通 ⇒ 该机对公网几乎无入站（仅白名单/Tailscale）。
+- 结论链：CF 回源 `box-direct` → 该记录橙云 → 真实源站端口被封 → **521**。
+  所有共用 `-direct` origin 的站点同时 521 ⇒ 用户说的「cloudflared 构建的网站全部 521」
+  与 cloudflared 无关，是**公网入站收敛**这一个动作把整批站点打掉的。nginx 升级纯属时间巧合。
+- 修复（保持「只允许组网」的安全目标）：① Zero Trust → 该 tunnel → Public Hostnames 加
+  `box.shiroko.one → http://127.0.0.1:5877`；② SaaS 面板把每个自定义主机名的「源服务器」
+  从 `xxx-direct.337845818.best` 改为 `ba34e35d-e517-498a-b2cd-7275c22e354e.cfargotunnel.com`。
+  注意不能把 `-direct` 改成「灰云 CNAME 到 cfargotunnel」——tunnel 路由要求橙云，SaaS origin 又
+  要求非橙云，两者冲突，必须直接在 origin 字段填 cfargotunnel。
+
+**⚠️ 纠正（官方文档）**
+- 上一条的后半段判断错了。CF for SaaS 文档明确：custom origin **必须**是该账号下
+  **proxied（橙云）的 A / AAAA / CNAME** 记录，不能用 IP。
+  ⇒ `box-direct.337845818.best` 是橙云，**格式上完全正确**，不是配置错误。
+  用 tunnel 的正确形态就是「橙云 CNAME → `<uuid>.cfargotunnel.com`」，所以那条路径依然成立，
+  只是理由不是「橙云错了」。
+- 真正断点仍是：`23.94.211.138` 的 **443 从公网不可达**（实测 timeout）。
+  但用户贴的 `iptables -S INPUT` 里**只有 8118 / 5877 两条 DROP，没有 443**
+  ⇒ 对 443 的封锁来自 iptables 之外（云厂商安全组 / 上游 / 其他链），或者 nginx 压根没监听 443。
+- 我上一轮的探测命令 `grep ':(80|5877|18080)'` **漏了 443**，这是取证缺口，需要补
+  `ss -tlnp | grep -E ':(443|80|5877)'` + `systemctl is-active nginx`。
+- 注意：SaaS 回源默认 Host = 原始自定义主机名（box.shiroko.one），而 tunnel 的 Public Hostname
+  只能从账号内 zone 选（shiroko.one 不在 CF）⇒ 走 tunnel 时必须用 Origin Rule / 源站主机头覆盖，
+  否则 tunnel 会 404。
+
+**最终根因（用户自查确认）：nginx 停了 11 小时**
+- 时间线：`10-22 00:12:43 Started`（升级后）→ `02:31:10 Stopping...` →
+  `02:31:15 Stopping timed out. Terminating.` → `Failed with result 'timeout'` → `Stopped`
+  → **中间 11 小时无任何记录** → `13:34:42` 用户手动 `systemctl start` 才起来。
+- ⇒ 全站 521 的直接原因就是 nginx 不在 443 监听；CF 回源 `box-direct`（橙云 A → 23.94.211.138:443）
+  拿不到东西。cloudflared/tunnel 全程健康且**从未参与这条链路**。
+- 重启后实测：`box.shiroko.one` 连续 3 次 200，`box-direct` 200，源站 443 OPEN。
+- 教训（我的误判链，值得记住）：排障时先确认「443 上跑的是什么、进程在不在」（`ss -tlnp` +
+  `systemctl is-active nginx`），再往 DNS/CDN/tunnel 方向挖。这次因为 CNAME 指向第三方 SaaS
+  + cloudflared 恰好健康，被带了很远。
+- 遗留技术债：
+  ① `listen 443 ssl http2` 在 1.25.1+ 已废弃 → 改 `listen 443 ssl;` + `http2 on;`；
+  ② `Failed to parse PID from file /run/nginx.pid: Invalid argument` —— 大概率是上次 SIGKILL
+     残留的 pid 文件，配合 `TimeoutStopSec` 过短（5s 就 Terminating）导致 stop 卡死；
+  ③ 全站无可用性监控（11 小时空窗没人知道）→ 建议外部 uptime + cron watchdog
+     `*/5 * * * * systemctl is-active --quiet nginx || systemctl start nginx`。
+
 **6) 窄屏覆盖被作用域块压死（真 bug，已修）**
 - 现象：`@media (max-width:640px)` 里把 `--tb-deco` 全写 none，手机上却照样是桌面装饰层。
 - 根因：媒体查询**不提升特异性**。作用域块 `html[data-theme-style][data-page-scope="box"]`
@@ -49,3 +167,14 @@
 - 手机端最终决定**不放装饰层**：试过顶栏与卡片之间那条 35px 带子，box 页 OK、question/admin
   页卡片从 y=110 起就切半个 → 变成黏在卡片边的粉色碎块。改用加强版底纹（透明度 ×1.9、格子 180px）。
 - 埋点：`gofmt -l internal/theme` 会报 `slots_test.go`（它是 CRLF），新增文件是 LF，别顺手格式化它。
+
+## 站内公告功能（配置驱动）
+
+- 新增 `[announcement]` 段（content/start/end），改完重启生效；判定全在服务端按 time.Now()。
+- 改动：conf/announcement.go（解析+Active+单测）、conf.Init MapTo、keynorm sectionKeySets 登记（漏了会误报未知段）、
+  template.FuncMap 新增 `announcement`（返回安全 HTML，空串 falsy 配 `{{ with }}`）、
+  internal/template/announcement.go（切段转义→URL 包链接，不能「先转义再正则」否则 &#34; 被吞进 URL）、
+  header.html 导航下方插 `uk-container-xsmall` 容器包 `.tb-announce`、base.css 样式（StaticVersion → 20261022a）。
+- 时间格式：`2006-01-02 15:04` / 带秒 / 纯日期 / RFC3339；裸时间按服务器本地时区（容器是 UTC），启动 INFO 打印解析结果。
+- 时间写错只 WARN 关公告不阻断启动（与未知键口径一致）；窗口左闭右开。
+- 预览验证：TEST_PREVIEW=1 + 临时 test 设 conf.Announcement 渲染 question/list，chrome --headless=old 截图 OK（亮/暗都看过）。