200 lines
4.2 KiB
Markdown
200 lines
4.2 KiB
Markdown
# Docker 启动与部署说明
|
||
|
||
## 固定入口
|
||
|
||
本项目固定使用 Docker Compose 项目名 `hot-comments-tool`，服务入口固定为：
|
||
|
||
```bash
|
||
http://localhost:8000
|
||
```
|
||
|
||
启动或重建：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
curl -f http://localhost:8000/health
|
||
```
|
||
|
||
查看容器：
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
正常情况下只需要看到一个应用容器：`hot-comments-tool-app-1`。
|
||
|
||
## 端口占用排查
|
||
|
||
如果 `8000` 被占用，先确认是不是本项目容器：
|
||
|
||
```bash
|
||
lsof -nP -iTCP:8000 -sTCP:LISTEN
|
||
docker compose ps
|
||
```
|
||
|
||
如果是旧的同项目容器，执行：
|
||
|
||
```bash
|
||
docker compose down
|
||
docker compose up -d --build
|
||
```
|
||
|
||
不要临时改到 `8001`，否则浏览器验收和文档记录会混乱。
|
||
|
||
## 环境变量
|
||
|
||
Docker Compose 读取 `.env`，不要把真实 `.env` 提交到 Git。
|
||
|
||
首次启动前可以从示例文件复制：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
必须配置：
|
||
|
||
```text
|
||
TIKHUB_API_KEY=
|
||
AI_BASE_URL=
|
||
AI_API_KEY=
|
||
AI_MODEL=
|
||
```
|
||
|
||
## 数据目录
|
||
|
||
SQLite 数据固定挂载整个目录：
|
||
|
||
```yaml
|
||
./data:/app/data
|
||
```
|
||
|
||
不要只挂载单个 `app.db` 文件。SQLite WAL 模式会生成：
|
||
|
||
```text
|
||
data/app.db
|
||
data/app.db-wal
|
||
data/app.db-shm
|
||
```
|
||
|
||
这三个文件必须在同一个挂载目录内。
|
||
|
||
## 重置本地验收数据库
|
||
|
||
仅在确认不需要保留历史任务后执行：
|
||
|
||
```bash
|
||
docker compose down
|
||
rm -f data/app.db data/app.db-wal data/app.db-shm
|
||
docker compose up -d --build
|
||
curl -f http://localhost:8000/health
|
||
```
|
||
|
||
重置后历史任务会消失，首页任务列表会从空状态开始。
|
||
|
||
## 验收命令
|
||
|
||
```bash
|
||
.venv/bin/python -m pytest tests/unit tests/integration -q
|
||
docker compose up -d --build
|
||
curl -f http://localhost:8000/health
|
||
```
|
||
|
||
## 公网部署决策清单
|
||
|
||
上线前必须确认以下决策，未经确认不要直接开放公网：
|
||
|
||
1. 部署方式：云服务器 Docker Compose、PaaS 平台，还是临时内网穿透演示。
|
||
2. 访问控制：是否需要访问密码 / 简单登录，或只在可信网络内演示。
|
||
3. 成本控制：公网用户是否允许直接消耗真实 TikHub 和 AI Key。
|
||
4. Demo 数据：公网环境使用脱敏 Demo 数据，还是允许展示真实抓取结果。
|
||
5. 数据生命周期：SQLite 数据是否需要持久保留，以及如何备份 / 重置。
|
||
|
||
当前建议：在上述问题确认前，只做本地 Docker 验收和部署准备，不把端口直接暴露到公网。
|
||
|
||
## 公网云服务器部署候选方案
|
||
|
||
如果确认采用云服务器 Docker Compose，可按以下步骤执行。
|
||
|
||
上线前准备：
|
||
|
||
```bash
|
||
git pull
|
||
cp .env.example .env
|
||
```
|
||
|
||
在 `.env` 中填写真实 Key：
|
||
|
||
```text
|
||
TIKHUB_API_KEY=
|
||
AI_BASE_URL=
|
||
AI_API_KEY=
|
||
AI_MODEL=
|
||
```
|
||
|
||
启动：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
curl -f http://127.0.0.1:8000/health
|
||
```
|
||
|
||
如果服务器安全组直接开放端口，公网入口为：
|
||
|
||
```text
|
||
http://服务器公网 IP:8000
|
||
```
|
||
|
||
也可以用 Nginx 反向代理到本机 `127.0.0.1:8000`。
|
||
|
||
注意：
|
||
|
||
- 第一版公网不加访问控制，任何知道地址的人都可以访问页面。
|
||
- 创建任务会消耗真实 TikHub 和 AI Key。
|
||
- 系统仍保持同一时间只允许一个 running 任务，避免多人同时触发造成成本和稳定性问题。
|
||
|
||
## 初始化 Demo 数据
|
||
|
||
公网演示建议先初始化脱敏 Demo 数据：
|
||
|
||
```bash
|
||
docker compose exec app python -m app.demo_seed
|
||
```
|
||
|
||
Demo 数据特点：
|
||
|
||
- 使用脱敏真实感评论文本。
|
||
- 不保存作者昵称、平台原始评论 ID、原始内容 URL 或 raw sensitive data。
|
||
- 可以和新创建的真实任务同时出现在任务列表中。
|
||
|
||
## 数据库异常备份与恢复
|
||
|
||
如果页面出现数据库不可用提示，先不要删除 `data` 目录。
|
||
|
||
系统会优先备份现有 SQLite 文件到：
|
||
|
||
```text
|
||
data/corrupt-backups/
|
||
```
|
||
|
||
手动诊断：
|
||
|
||
```bash
|
||
docker compose exec app python - <<'PY'
|
||
from app.db import engine
|
||
from sqlalchemy import text
|
||
with engine.connect() as c:
|
||
print(c.execute(text("PRAGMA integrity_check")).fetchall())
|
||
print(c.exec_driver_sql("PRAGMA wal_checkpoint(TRUNCATE)").fetchall())
|
||
PY
|
||
```
|
||
|
||
如果需要重新初始化演示数据：
|
||
|
||
```bash
|
||
docker compose down
|
||
mv data/app.db data/corrupt-backups/app.db.manual.bak
|
||
rm -f data/app.db-wal data/app.db-shm
|
||
docker compose up -d --build
|
||
docker compose exec app python -m app.demo_seed
|
||
```
|