# 🏆 里程碑 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
```