docs: milestone V1 snapshot - full service state, auth architecture, recovery guide
This commit is contained in:
fxy
200
milestone_v1.md
Normal file
200
milestone_v1.md
Normal file
@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user