server-ops/milestone_v1.md

🏆 里程碑 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 + Calibre-Web 配置）

最新 commit: a6e85c6 (Milestone V1)
回滚命令: git checkout a6e85c6 -- auth_proxy/
         git checkout a6e85c6 -- milestone_v1.md

---

六、Calibre-Web 配置

项目	值
域名	books.xybkwd.top
端口	8083（Docker）
镜像	lscr.io/linuxserver/calibre-web:latest
数据目录	/home/ubuntu/calibre-web/books/（映射到容器 /books）
配置目录	/home/ubuntu/calibre-web/config/（映射到容器 /config）
管理员	admin / admin123
语言	zh_Hans_CN（简体中文）
数据库路径	/books
上传功能	已开启

Docker 启动命令

docker run -d --name=calibre-web \
  -e PUID=1000 -e PGID=1000 \
  -p 8083:8083 \
  -v /home/ubuntu/calibre-web/config:/config \
  -v /home/ubuntu/calibre-web/books:/books \
  --restart unless-stopped \
  lscr.io/linuxserver/calibre-web:latest

Calibre-Web 踩坑记录

1. metadata.db 必须用 calibredb 创建，不要手动 sqlite3 CREATE TABLE
2. config_calibre_uuid 必须匹配 metadata.db 中 library_id.uuid
3. 上传卡死通常是 metadata.db 版本不兼容（宿主机 calibre vs 容器内）
4. 重置容器后 settings 表配置会丢失（上传、语言、标题需重新设置）

---

六、完全恢复步骤

# 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

---

七、调试命令模板

# 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