From a6e85c69d37299532eac8160081eaa006492ef4f Mon Sep 17 00:00:00 2001 From: fxy Date: Mon, 15 Jun 2026 20:36:01 +0800 Subject: [PATCH] docs: milestone V1 snapshot - full service state, auth architecture, recovery guide --- milestone_v1.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 milestone_v1.md diff --git a/milestone_v1.md b/milestone_v1.md new file mode 100644 index 0000000..40648b9 --- /dev/null +++ b/milestone_v1.md @@ -0,0 +1,200 @@ +# 🏆 里程碑 V1 — 栖云个人数据中心 + +> **时间**：2026-06-15 20:33 +> **确认人**：冯星源 +> **状态**：所有服务正常运行，认证架构按预期工作 + +--- + +## 一、认证架构 + +``` +浏览器 → Caddy v2.11.4（HTTPS 终止 + 路由） + ├─ 有 sess cookie → 直接放行到后端（7天免登录） + ├─ 无 cookie → 302 跳转到 auth.xybkwd.top/login + └─ auth.xybkwd.top → auth_proxy:9002（登录页 + 签发 cookie） +``` + +### 认证流程 +1. 用户访问任意受保护服务 → 无 cookie → 302 到 `auth.xybkwd.top/login?redirect=原地址` +2. 用户输入 `fxy` / `Qiyun2025!` → auth_proxy 验证 → 设置 `sess` cookie → 302 回原地址 +3. 浏览器带 cookie 访问原地址 → Caddy 匹配 `@authed { header Cookie "sess=*" }` → 直接放行 +4. Cookie 7 天有效，到期后重复步骤 1 + +### Cookie 参数 +| 参数 | 值 | +|:---|:---| +| Name | `sess` | +| Value | `base64(payload).hmac_sig` | +| Domain | `.xybkwd.top`（跨子域） | +| Path | `/` | +| HttpOnly | ✅ | +| SameSite | `Lax` | +| Max-Age | 604800（7天） | + +--- + +## 二、服务清单 + +| # | 服务 | 域名 | 端口 | 后端类型 | 认证方式 | Gitea Commit | +|:---:|:---|:---|:---:|:---|:---|:---:| +| 1 | **Caddy** | 所有域名 | 80/443 | 反向代理 | HTTPS 自动证书 | nav-page `1a80249` | +| 2 | **auth_proxy** | auth.xybkwd.top | 9002 | Python http.server | Cookie Session | server-ops `195954c` | +| 3 | **Gitea** | gitea.xybkwd.top | 3000 | Gitea 二进制 | Cookie 跳过 | — | +| 4 | **Dashboard** | dashboard.xybkwd.top | 9000 | Python Flask | Cookie 跳过 | — | +| 5 | **Memos** | memo.xybkwd.top | 5230 | Docker | 自身登录 | — | +| 6 | **栖云导航** | nav.xybkwd.top | 静态 | Caddy file_server | Cookie 跳过 | — | +| 7 | **每日要闻** | brief.xybkwd.top | 静态 | Caddy file_server | Cookie 跳过 | — | +| 8 | **Todo API** | nav.xybkwd.top/api | 9001 | Python | Cookie 跳过 | — | +| 9 | **Vaultwarden** | vault.xybkwd.top | 8088 | Docker | 自身登录 | — | +| 10 | **Halo 博客** | www.xybkwd.top | 8090 | Docker | 自身登录 | — | +| 11 | **Calibre-Web** | books.xybkwd.top | 8083 | Docker | Cookie 跳过 | — | +| 12 | **AI Chat** | chat.xybkwd.top | 8900 | Python | Cookie 跳过 | — | +| 13 | **灵感收集器** | — | — | Python/cron | — | inspiration-collector | +| 14 | **系统备份** | — | — | shell/cron | — | — | + +### 服务依赖关系 + +``` +Caddy v2.11.4（HTTPS + 路由） + ├── auth.xybkwd.top:443 ──→ auth_proxy:9002（登录页，无其他依赖） + ├── gitea.xybkwd.top:443 ──→ Gitea:3000 + ├── dashboard.xybkwd.top:443 ──→ dashboard:9000 + ├── memo.xybkwd.top:443 ──→ Memos Docker:5230 + ├── nav.xybkwd.top:443 ──→ 静态文件 /var/www/nav + API → todo:9001 + ├── brief.xybkwd.top:443 ──→ 静态文件 /var/www/nav + ├── vault.xybkwd.top:443 ──→ Vaultwarden Docker:8088 + ├── www.xybkwd.top:443 ──→ Halo Docker:8090 + ├── books.xybkwd.top:443 ──→ Calibre-Web Docker:8083 + └── chat.xybkwd.top:443 ──→ AI Chat Python:8900 +``` + +--- + +## 三、核心文件 + +| 文件 | 服务器路径 | Gitea 仓库路径 | 功能 | +|:---|:---|:---|:---| +| **Caddyfile** | `/etc/caddy/Caddyfile` | `fxy/nav-page/Caddyfile` | 反向代理 + Cookie 路由 + HTTPS | +| **auth_proxy.py** | `/home/ubuntu/auth_proxy.py` | `beast/server-ops/auth_proxy/auth_proxy.py` | 登录页 + Cookie 签发 | +| **auth_proxy.service** | `/etc/systemd/system/auth_proxy.service` | `beast/server-ops/auth_proxy/auth_proxy.service` | systemd 服务管理 | + +--- + +## 四、关键配置常量 + +| 配置项 | 值 | 说明 | +|:---|:---|:---| +| 服务器 IP | `43.163.225.30` | 东京云服务器 | +| SSH 密钥 | `C:/Users/32779/Desktop/ssh_new.pem` | 本地私钥路径 | +| 登录用户名 | `fxy` | basicauth + auth_proxy 通用 | +| 登录密码 | `Qiyun2025!` | **不要明文存储** | +| bcrypt hash | `$2a$14$0U13bqD7CgmZe7jcBQAUHehV2M6qrotbxERgDrHgzLxSXtmRX/YUK` | Caddy basic_auth 用 | +| auth_proxy 监听 | `127.0.0.1:9002` | 仅本地访问 | +| nav 静态文件根 | `/var/www/nav/` | 导航页 + 每日要闻 | + +--- + +## 五、Gitea 仓库锚点 + +### nav-page（Caddyfile） +``` +最新 commit: 1a80249 +消息: refactor: unified login-first experience +回滚命令: git checkout 1a80249 -- Caddyfile +``` + +### server-ops（auth_proxy） +``` +最新 commit: 195954c +消息: fix: auth_proxy Cache-Control no-cache + POST redirect fallback +回滚命令: git checkout 195954c -- auth_proxy/ +``` + +--- + +## 六、完全恢复步骤 + +```bash +# 1. 克隆仓库 +cd /tmp +git clone http://gitea.xybkwd.top/fxy/nav-page.git +git clone http://gitea.xybkwd.top/beast/server-ops.git + +# 2. 恢复 Caddy +sudo cp nav-page/Caddyfile /etc/caddy/Caddyfile +sudo caddy reload --config /etc/caddy/Caddyfile + +# 3. 恢复 auth_proxy +sudo cp server-ops/auth_proxy/auth_proxy.py /home/ubuntu/ +sudo cp server-ops/auth_proxy/auth_proxy.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl restart auth_proxy +``` + +--- + +## 七、调试命令模板 + +```bash +# 1. 验证登录页 +curl -sk -o /dev/null -w '%{http_code}' https://auth.xybkwd.top/login +# 期望值: 200 + +# 2. 验证认证拦截 +curl -sk -o /dev/null -w '%{http_code}' https://brief.xybkwd.top/ +# 期望值: 302（重定向到登录页） + +# 3. 登录并获取 cookie +curl -sk -c /tmp/v1_cookies.txt -X POST \ + -d 'username=fxy&password=Qiyun2025!' \ + -d 'redirect=https://brief.xybkwd.top/' \ + https://auth.xybkwd.top/login +# 期望值: 302 + Set-Cookie + +# 4. 验证 cookie 免登录 +curl -sk -o /dev/null -w '%{http_code}' \ + --cookie /tmp/v1_cookies.txt https://brief.xybkwd.top/ +# 期望值: 200 + +curl -sk -o /dev/null -w '%{http_code}' \ + --cookie /tmp/v1_cookies.txt https://dashboard.xybkwd.top/ +# 期望值: 200 + +curl -sk -o /dev/null -w '%{http_code}' \ + --cookie /tmp/v1_cookies.txt https://gitea.xybkwd.top/ +# 期望值: 200 +``` + +--- + +## 八、已知限制 + +1. **Cookie 仅检查存在性**，不验证 HMAC 签名（个人服务器可接受） +2. **auth_proxy 单进程** Python http.server，高并发可能阻塞 +3. **无 basicauth 兜底**，完全依赖 cookie，cookie 丢失需重新登录 +4. **auth_proxy 无自动重启**，异常退出需 systemd 重启 +5. **Dashboard 缺少 WebSocket 支持**，实时更新可能不稳定 + +--- + +## 九、历史 Git 记录（2026-06-15 全量） + +### nav-page commit 线 +``` +1a80249 refactor: unified login-first experience +a86991a feat: cookie + basicauth dual-auth (7-day session) +f43abe9 fix: restore basic_auth with bcrypt (Caddy v2.11 compatible) +41f8ded rollback: revert auth_proxy to direct proxy (no auth) +9462963 auth: replace basicauth with cookie session auth_proxy +6c35f31 fix: unify ebook library card status text to 运行中 +``` + +### server-ops commit 线 +``` +195954c fix: auth_proxy Cache-Control no-cache + POST redirect fallback +438245a rollback: revert auth_proxy, restore direct proxy +858a948 auth: add auth_proxy v2 with cookie session auth +df7d64d fix: remove basicauth from memo.xybkwd.top (has own auth) +846dcf7 fix: add missing brief.xybkwd.top with basicauth +```