docs: 更新 README 与线上部署运维说明，新增 .gitignore

- README: 新架构图/端口表/目录结构/双缓存机制/waitress/部署与验证步骤/版本要点 - docs/部署与运维.md: 线上服务器的实际路径、缓存策略、迁移 8 步、日志与变更记录 - .gitignore: 忽略 source/cache/、tokens.json、cookies.txt、__pycache__
2026-09-13 02:26:35 +08:00
parent 212adb1e25
commit 1b2071d78b
3 changed files with 251 additions and 20 deletions
@@ -0,0 +1,127 @@
+# 线上部署与运维（hk）
+
+> 记录线上服务器 `hk`（`103.24.218.119:10526`）的实际路径、缓存策略与迁移步骤。
+> 架构与代码结构见根目录 [README](../README.md)。
+
+## 对外入口
+
+统一入口：`https://openapi.rrrosmontis.icu`（nginx 监听 80/443）
+
+| 路径 | 链路 |
+|---|---|
+| `/pixiv/get_image?id=xxx` | `127.0.0.1:9008`（main.py 聚合层）→ `127.0.0.1:9007`（pixiv） |
+| `/bilibili/get_video?bv=xxx` | `127.0.0.1:9008`（main.py 聚合层）→ `127.0.0.1:9006`（bilibili） |
+| `/img-master/`、`/img-original/` | nginx 直接反代 `i.pximg.net`（无本地后端） |
+| `/` | `127.0.0.1:9008`（302 跳转文章页） |
+
+- 其余在服站点：`sqy.bu4.ren`、`xxx.aeolianchi.me`
+- 已删除的 vhost：`kim1.work`、`zxx.aeolianchi.me`（2026-09-12）
+- 历史域名 `api.bu4.ren` / `pixiv.bu4.ren` / `apixiv.bu4.ren` 已合并进 `openapi.rrrosmontis.icu`
+
+## 进程与端口
+
+三个服务**全部只绑 `127.0.0.1`**，对外仅 nginx 的 443/80。
+
+| systemd 单元 | 源码 | 监听 | 说明 |
+|---|---|---|---|
+| `openapi.service` | `source/main.py` | `:9008` | 聚合层（aiohttp，纯转发，唯一入口） |
+| `pixiv.service` | `source/pixiv/pixiv.py` | `:9007` | Flask，由 waitress（8 线程）承载 |
+| `bilibili.service` | `source/bilibili/bilibili.py` | `:9006` | aiohttp + yt-dlp |
+| `pixiv-token-refresh.service` | `source/pixiv/refresh_token.py` | — | 常驻刷新 Pixiv OAuth token |
+| `bilibili-refresh.service` | `source/bilibili/refresh_cookie.py` | — | 常驻刷新 bilibili cookie |
+
+## 目录结构
+
+```
+/home/openapi/
+├── source/
+│   ├── main.py                       聚合层源码（2026-09-12 从 source/openapi/ 上移至此）
+│   ├── pixiv/
+│   │   ├── pixiv.py                  图像代理（Flask）
+│   │   ├── refresh_token.py          token 刷新守护
+│   │   └── tokens.json               Pixiv OAuth token（敏感，权限 600，不入库）
+│   ├── bilibili/
+│   │   ├── bilibili.py               视频代理（aiohttp + yt-dlp）
+│   │   ├── cookies.txt               bilibili cookie（敏感，不入库）
+│   │   ├── refresh_cookie.py         cookie 刷新守护
+│   │   └── qr_login*.py              扫码登录工具（cookie 失效时人工重登用）
+│   └── cache/                        运行时缓存（不入库）
+│       ├── pixiv/images              pixiv 图片缓存（代码中为 ../cache/pixiv/images）
+│       └── bilibili/                 bilibili 视频缓存（上限 2 GiB / TTL 7 天）
+├── systemd/                          5 个单元文件的归档副本（与 /etc/systemd/system/ 保持一致）
+├── nginx/                            宝塔导出的历史存档，非生效路径
+├── cert/                             SSL 证书
+├── env/                              Python 环境（general + env_general.tar.gz 整包）
+└── 备份说明.txt                      本文件的历史版本（旧端口/旧路径，仅供参考）
+
+/home/images -> /home/openapi/source/cache/pixiv/images    便捷软链
+```
+
+## 缓存机制
+
+**pixiv（图片）**：`check_cache()` 以 glob 命中即直接回文件；未命中按 `官方 App API → pixiv.re → pixiv.cat` 三级回退抓取，落盘用 `.tmp` + `os.replace` 原子写。
+
+**bilibili（视频）**：以 BV 号为键缓存到 `source/cache/bilibili/{BV}.mp4`
+
+- 命中即复用、不再下载
+- 未命中才调 yt-dlp，先下载到缓存目录内的隐藏暂存目录 `.dl-XXXX`，成功后原子 rename 落盘
+- 无论成功 / 失败 / 超时都 `rmtree` 该暂存目录
+  （2026-09-12 修复：原实现从不清理 tmpdir，每次取视频都会把完整视频永久留在 `/tmp`，属无上限磁盘泄漏）
+- 淘汰策略：单文件 7 天未访问过期 + 总量超过 2 GiB 时按 mtime 从最旧开始删
+- 运维接口：`curl -s 127.0.0.1:9006/bilibili/cache_info`
+
+## nginx
+
+| 文件 | 作用 |
+|---|---|
+| `/etc/nginx/conf.d/openapi.rrrosmontis.icu.conf` | 统一入口站点（`proxy_pass` → `127.0.0.1:9008`） |
+| `/etc/nginx/conf.d/00-websocket.conf` | `$connection_upgrade` map 定义（**必须存在**） |
+| `/home/openapi/nginx/**` | 宝塔导出的历史存档，非生效路径 |
+
+## Python 环境
+
+- `/home/openapi/env/general` —— 三服务共用（flask / waitress / aiohttp / httpx / yt-dlp）
+- `/home/openapi/env/env_general.tar.gz` —— 环境整包（迁移用）
+- 注意：pixiv 现由 **waitress** 承载（`pip install waitress`，纯 Python 线程池），不再使用 Flask 开发服务器
+  （开发服务器是 thread-per-request 无上限，受控线程池更适合长期运行）
+
+## 迁移到新服务器
+
+1. **环境**：解压 `env/env_general.tar.gz`，直接使用其 `bin/python`（依赖齐全，含 waitress）
+2. **源码**：恢复 `source/{main.py,pixiv/,bilibili/}` 到 `/home/openapi/source/`
+3. **systemd**：恢复 `systemd/*.service` 到 `/etc/systemd/system/`，`daemon-reload` + `enable` + `start`
+4. **nginx**：套用 `conf.d/openapi.rrrosmontis.icu.conf`（并确保 `00-websocket.conf` 的 map 存在）
+5. **SSL**：恢复 `cert/<域名>/` 到 `/etc/nginx/cert/<域名>/`
+6. **凭据**：放回 `source/pixiv/tokens.json`(600) 与 `source/bilibili/cookies.txt`
+7. **软链**：`ln -s /home/openapi/source/cache/pixiv/images /home/images`
+8. **验证**：
+   ```bash
+   curl -k "https://openapi.rrrosmontis.icu/pixiv/get_image?id=xxx"
+   curl -k "https://openapi.rrrosmontis.icu/bilibili/get_video?bv=BV16a41157Q4"
+   ```
+
+## 日志
+
+```
+/var/log/openapi.log            /var/log/pixiv.log            /var/log/bilibili.log
+/var/log/bilibili_refresh.log   /var/log/pixiv_token_refresh.log
+```
+
+缓存命中/落盘会在 `bilibili.log` 打印 `cache HIT / MISS / STORE`（已加 `flush`，实时可见）。
+
+## 变更记录
+
+**2026-09-12**
+
+- 端口重排 `9888 / 9088 / 19990 → 9008 / 9007 / 9006`（全部仅 `127.0.0.1`）
+- pixiv 曾误绑 `0.0.0.0:9088` 对外裸奔（绕过 nginx 日志与限流），已收口为 `127.0.0.1`
+- 主入口 `main.py` 由 `source/openapi/` 上移到 `source/`；systemd `WorkingDirectory` 同步
+- pixiv 的 `IMAGE_DIR` 由硬编码 `/home/pixiv/images` 改为相对 `../cache/pixiv/images`，并建 `/home/images` 软链
+- bilibili 新增真缓存（`../cache/bilibili`）并修复 `/tmp` 泄漏，新增 `cache_info` 接口
+- pixiv 改用 waitress 8 线程
+- 删除 `kim1.work` / `zxx.aeolianchi.me` 两个 vhost
+- 清理历史 `.bak` / `__pycache__` / 空日志等冗余文件
+
+**2026-09-02** 新增 `pixiv-token-refresh`；补 `/img-original/` 反代（App API 原图路径）
+
+**2026-07-31** 三服务迁移落位（Python 环境合并为单一 `general`）