meijiali/hot_comment_radar

Fork 0

Files

T

meijiali 9935f67080 feat: 完善 MVP-2 演示和进度体验

2026-07-03 16:57:39 +08:00

3.6 KiB

Raw Blame History

Docker 启动与部署说明

固定入口

本项目固定使用 Docker Compose 项目名 hot-comments-tool，服务入口固定为：

http://localhost:8000

启动或重建：

docker compose up -d --build
curl -f http://localhost:8000/health

查看容器：

docker compose ps

正常情况下只需要看到一个应用容器：hot-comments-tool-app-1。

端口占用排查

如果 8000 被占用，先确认是不是本项目容器：

lsof -nP -iTCP:8000 -sTCP:LISTEN
docker compose ps

如果是旧的同项目容器，执行：

docker compose down
docker compose up -d --build

不要临时改到 8001，否则浏览器验收和文档记录会混乱。

环境变量

Docker Compose 读取 .env，不要把真实 .env 提交到 Git。

首次启动前可以从示例文件复制：

cp .env.example .env

必须配置：

TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=

数据目录

SQLite 数据固定挂载整个目录：

./data:/app/data

不要只挂载单个 app.db 文件。SQLite WAL 模式会生成：

data/app.db
data/app.db-wal
data/app.db-shm

这三个文件必须在同一个挂载目录内。

重置本地验收数据库

仅在确认不需要保留历史任务后执行：

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

重置后历史任务会消失，首页任务列表会从空状态开始。

验收命令

.venv/bin/python -m pytest tests/unit tests/integration -q
docker compose up -d --build
curl -f http://localhost:8000/health

公网云服务器部署

第一版公网演示使用云服务器 + Docker Compose，不增加登录或密码。

上线前准备：

git pull
cp .env.example .env

在 .env 中填写真实 Key：

TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=

启动：

docker compose up -d --build
curl -f http://127.0.0.1:8000/health

如果服务器安全组直接开放端口，公网入口为：

http://服务器公网 IP:8000

也可以用 Nginx 反向代理到本机 127.0.0.1:8000。

注意：

第一版公网不加访问控制，任何知道地址的人都可以访问页面。
创建任务会消耗真实 TikHub 和 AI Key。
系统仍保持同一时间只允许一个 running 任务，避免多人同时触发造成成本和稳定性问题。

初始化 Demo 数据

公网演示建议先初始化脱敏 Demo 数据：

docker compose exec app python -m app.demo_seed

Demo 数据特点：

使用脱敏真实感评论文本。
不保存作者昵称、平台原始评论 ID、原始内容 URL 或 raw sensitive data。
可以和新创建的真实任务同时出现在任务列表中。

数据库异常备份与恢复

如果页面出现数据库不可用提示，先不要删除 data 目录。

系统会优先备份现有 SQLite 文件到：

data/corrupt-backups/

手动诊断：

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

如果需要重新初始化演示数据：

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

3.6 KiB Raw Blame History Unescape Escape