# 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
```

## 公网云服务器部署

第一版公网演示使用云服务器 + 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
```