Files

T

gavindiazandClaude Code f63c0c55c9 feat: Docker 化部署（nginx-proxy-manager 反代，单域名 /api 路由）

- docker-compose.yml: backend + frontend 两服务，挂 NPM 所在外部网络、不暴露宿主端口；
  data/uploads 用 bind mount 持久化（deploy/ 下，gitignored）
- backend/Dockerfile: python:3.12-slim + 清华 PyPI 镜像（ARG 可覆盖）
- frontend/Dockerfile: 多阶段 node:22 + npm ci + next build（NEXT_PUBLIC_API_BASE 构建期
  注入，npmmirror 默认）→ next start
- .env.example: 全量部署环境变量模板（compose 替换变量 + 后端密钥）
- deploy/README.md: 服务器部署手册（NPM 配置 / DNS / 数据迁移 / 运维 / 大陆网络）

Co-Authored-By: Claude Code <noreply@anthropic.com>

2026-10-25 15:35:20 +08:00

4.4 KiB

Raw Blame History

BookMate 云服务器部署手册（Docker + nginx-proxy-manager）

服务器已装 Docker 与 nginx-proxy-manager（NPM）。BookMate 由 backend（FastAPI:8000）与 frontend（Next.js:3000）两个容器组成，挂到 NPM 所在网络，由 NPM 用域名反代 + TLS。 不暴露任何宿主端口，不会和你服务器上的其它应用冲突。

0. 准备

把仓库放到服务器（二选一）：

# A. git 克隆（推荐，后续更新方便）
git clone https://code.aifunny.ltd/gavindiaz/my_bookmate.git /opt/bookmate
cd /opt/bookmate

# B. 或从本机拷贝（不含 .git 也行）
#   scp -r ./bookmate user@server:/opt/

1. 迁移现有数据（保留书库 / 对话 / 向量）

只迁移 backend/data（含 bookmate.db）和 backend/uploads（EPUB 原文件）。先确认本机后端已停止（避免 db 锁），再拷贝。

# 在服务器上（目录结构照做）
mkdir -p /opt/bookmate/deploy/data /opt/bookmate/deploy/uploads

# 本机执行（把路径换成你的）
scp backend/data/bookmate.db          user@server:/opt/bookmate/deploy/data/
scp -r backend/uploads/.              user@server:/opt/bookmate/deploy/uploads/

不迁移也能跑：服务器从空书库开始，之后在网页里重新导入即可。

2. 配置 .env

cd /opt/bookmate
cp .env.example .env
# 编辑 .env，必改项：
#   NEXT_PUBLIC_API_BASE=https://你的域名/api
#   NPM_NETWORK=  ← 服务器上 `docker network ls` 查到 NPM 所在网络名
#   SITE_PASSWORD= ← 站点访问密码（必须设，否则任何人可访问）
#   DEEPSEEK_API_KEY / OPENROUTER_API_KEY / EMBEDDING_API_KEY / RERANK_API_KEY 等

3. 构建并启动

cd /opt/bookmate
docker compose up -d --build
docker compose ps          # 两个容器都应为 Up
# 无 NPM 时直连验证：
curl http://localhost:8000/api/health   # {"status":"ok"}
curl http://localhost:3000              # 前端 HTML

4. NPM 反向代理 + TLS

NPM 网页（通常 http://服务器IP:81）→ Hosts → Add Proxy Host：

Domain Names：bookmate.example.com（改成你的）
Forward Hostname / Port：
- 根路径：frontend / 3000
Custom Locations（添加两段，最长前缀优先）：

Location Forward Hostname Port

/api backend 8000

/ frontend 3000
SSL：Request a new SSL Certificate → Let's Encrypt → 勾选 Force SSL。

Location	Forward Hostname	Port
`/api`	`backend`	`8000`
`/`	`frontend`	`3000`

SSE 流式与文件上传都是普通 HTTP，NPM 无需 websocket 特殊配置。

5. DNS

把 bookmate.example.com 的 A 记录指向服务器公网 IP，等解析生效即可访问 https://bookmate.example.com。

6. 验证

打开 https://bookmate.example.com → 出现登录页 → 输入 SITE_PASSWORD。
书库应显示迁移过来的书；打开一本书能看到迁移的对话。
上传一本新 EPUB → 对话提问 → 确认流式回答与引用正常。
发一条「第二大脑 / AI 助手」消息 → 确认工具（bm_*）能调用。

7. 日常运维

# 更新到最新代码并重建
cd /opt/bookmate
git pull
docker compose up -d --build

# 看日志
docker compose logs -f backend
docker compose logs -f frontend

# 备份（只备份数据即可，镜像可重建）
tar czf bookmate-data-backup.tgz deploy/data deploy/uploads

大陆网络

Dockerfile 已把国内源烘焙成默认值（可在构建时用 --build-arg 覆盖为官方源）：

backend 的 pip：默认 https://pypi.tuna.tsinghua.edu.cn/simple
frontend 的 npm：默认 https://registry.npmmirror.com

基础镜像（python:3.12-slim / node:22-alpine）来自 Docker Hub，大陆直连可能很慢/失败：

临时用代理拉一次后即缓存（docker pull python:3.12-slim && docker pull node:22-alpine）；
或给 Docker 配置 registry 镜像加速（如阿里云容器镜像服务），长期更稳。

常见问题

NPM 连不上容器：NPM_NETWORK 没填对。docker network ls 确认 NPM 所在网络名，填到 .env 后 docker compose down && docker compose up -d 重建网络连接。
页面能开但接口 404：/api 的 Custom Location 没加，或 NEXT_PUBLIC_API_BASE 端口/域名与 NPM 配置不一致（它内联在构建产物里，改了要重新 build）。
向量没生效：确认 EMBEDDING_API_KEY / RERANK_API_KEY 已填；上传新书后后台会自动生成向量。

4.4 KiB Raw Blame History Unescape Escape