openapi/docs/部署与运维.md

线上部署与运维（hk）

记录线上服务器 hk（103.24.218.119:10526）的实际路径、缓存策略与迁移步骤。 架构与代码结构见根目录 README。

对外入口

统一入口：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）
/dufe/ginkgostu_sign_in	127.0.0.1:9008（main.py 聚合层）→ 127.0.0.1:9005（dufe 签到码查询，支持 GET|POST）
/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
ginkgo_sign_in.service	source/dufe/ginkgostu_sign_in/ginkgo_sign_in.py	:9005	银杏（DUFE）签到码查询，Flask + waitress（16 线程），GET|POST
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 失效时人工重登用）
│   ├── dufe/
│   │   └── ginkgostu_sign_in/
│   │       └── ginkgo_sign_in.py     银杏（DUFE）签到码查询服务（127.0.0.1:9005，GET|POST）
│   └── cache/                        运行时缓存（不入库）
│       ├── pixiv/images              pixiv 图片缓存（代码中为 ../cache/pixiv/images）
│       └── bilibili/                 bilibili 视频缓存（上限 2 GiB / TTL 7 天）
├── systemd/                          6 个单元文件的归档副本（与 /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/,dufe/} 到 /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. 验证：

   curl -k "https://openapi.rrrosmontis.icu/pixiv/get_image?id=xxx"
   curl -k "https://openapi.rrrosmontis.icu/bilibili/get_video?bv=BV16a41157Q4"
   curl -k "https://openapi.rrrosmontis.icu/dufe/ginkgostu_sign_in"   # 无参应返回 400 JSON
   

日志

/var/log/openapi.log            /var/log/pixiv.log            /var/log/bilibili.log
/var/log/ginkgo_sign_in.log     /var/log/bilibili_refresh.log /var/log/pixiv_token_refresh.log

缓存命中/落盘会在 bilibili.log 打印 cache HIT / MISS / STORE（已加 flush，实时可见）。

变更记录

2026-09-13

• 新增 dufe 银杏签到码查询服务：source/dufe/ginkgostu_sign_in/ginkgo_sign_in.py + ginkgo_sign_in.service（127.0.0.1:9005，Flask + waitress 16 线程，端点 GET|POST /dufe/ginkgostu_sign_in）
• 在聚合层 main.py 注册该端点：新增 DUFE_BACKEND 与 proxy_forward()（保留请求方法/请求体；原 proxy() 固定 GET 行为未改动）
• nginx 无需改动：location / 兜底已把 /dufe/... 转发给 127.0.0.1:9008

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）