mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-25 03:18:08 +00:00
39a0c626b6
本项目的生产部署是「多站点 + 统一入口 + 两层 TLS 终止」，此前只存在于 人和 agent 的临时记忆里 —— 换个人接手要重新摸索一遍，我这次就因此在 同一类问题上反复踩坑（误报「已修好」两次、并造成一次全站 TLS 故障）。 把机制写下来。 ## 内容 - §0 拓扑：两层 TLS 终止（公网入口机 + 内网网关机），并指出「改一层 ≠ 改完」 - §1 部署一个静态站的完整流程（内网 drop-in → 证书 → 公网 drop-in） 含若干踩过的坑：为何用 drop-in 而非改生成的主配置、 为何静态站必须 `try_files ... =404`（回落 index.html 会让不存在的路径 返回 200，监控与链接检查全都「通过」）、反代为何要关缓冲攒包 - §2 验收：**必须用 `--resolve` / `--host-resolver-rules` 走真实公网路径**。 内网 DNS 会把域名解析到内网机，直连 curl 测的是另一条路 —— 这正是我此前误报「已修好」的根因。附 Playwright 片段 （强调 `ignoreHTTPSErrors` 必须为 false，否则等于没测） - §3 证书续期：cron → 续期 → 钩子（内网 reload + 推公网），全自动； 以及**推送脚本必须保留的四道防线**（见下） - §4 管理后台接口：先取 schema 别猜字段名；路由表是**整表替换**； 写完要轮询验证（apply 是异步的）；系统管理的分组不能手工加条目 - §5 已知陷阱与事故复盘（6 条，均来自本项目真实故障） - §6 给 agent 的直读入口（llms.txt / 每页 .md，含两个必踩的坑） - §7 脱敏约定 ## 关于事故复盘 §5.1 记录了我这次造成全站 TLS 故障的根因：把 acme.sh 的证书目录名 （**字面含 `*`**）交给了 glob，glob 展开后误匹配到别的证书并写进全局默认 证书。由此提炼两条硬规则：字面 `*` 绝不用 glob；写生产前必须断言 「读到的是什么」。§5.3 记录了「删证书记录前先查全盘引用」—— 我漏了 /opt/ 导致推送脚本失效。 ## 脱敏 全文无真实域名、IP、token、云 AK/SK、实例 ID 与内部组件名， 一律占位符（`<PUBLIC_IP>` / `<GATEWAY_DATA>` 等）， 取值指向本机私有笔记与基础设施面板。已用脚本对 8 类模式做终审扫描： 仅 `127.0.0.1` / `0.0.0.0` / `example.com` 这类结构性取值保留。 技术论断均与线上实际配置或上游源码逐条核对（drop-in 指令、钩子行为、 后台接口语义），文档本身不构成新的未验证声明。