docs: milestone V1 snapshot - full service state, auth architecture, recovery guide

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
+```