后台运维指南

进入本机工程

cd /Users/liujingjie/AI-PRO/sanguo-cards

打开数据库终端

进入 psql 后输入 \q 退出。该方式不需要把数据库端口暴露到电脑。

docker compose --env-file Backend/.local/compose.env -f compose.yaml exec db psql -U sanguo -d sanguo

只读确认连接

这条只读命令已在本机验证。

docker compose --env-file Backend/.local/compose.env -f compose.yaml exec -T db psql -U sanguo -d sanguo -c 'SELECT current_database(), current_user, version();'

启动或更新后台

构建镜像、启动两个服务，并等待就绪。启动后刷新主页。

python3 Backend/manage.py start

查看运行状态

API 与 db 应显示 healthy。

python3 Backend/manage.py status

查看最近日志

只输出最近 80 行；日志可能包含运行信息，不要直接公开整份日志。

python3 Backend/manage.py logs

停止后台

停止 API 和数据库容器，账号数据保留。停止后网页和游戏云端服务暂时不可用。

python3 Backend/manage.py stop

生成数据库备份

生成带 UTC 时间戳的 .dump 文件，保存到 Backend/.local/backups/，成功后打印路径。备份包含账号与会话资料，请保存在私有位置。

python3 Backend/manage.py backup

启动全部后台服务

docker compose --env-file Backend/.local/compose.env -f compose.yaml up -d --build --wait --wait-timeout 180

列出容器状态

docker compose --env-file Backend/.local/compose.env -f compose.yaml ps

查看 API 日志

docker compose --env-file Backend/.local/compose.env -f compose.yaml logs --tail 80 api

持续跟随 API 日志

按 Ctrl+C 退出日志查看，服务继续运行。

docker compose --env-file Backend/.local/compose.env -f compose.yaml logs --tail 80 -f api

查看数据库日志

docker compose --env-file Backend/.local/compose.env -f compose.yaml logs --tail 80 db

只更新 API 与网页

替换 API 容器，数据库容器继续运行；更新时 API 会短暂不可用。新的网页随后部署并自动列入主页。

docker compose --env-file Backend/.local/compose.env -f compose.yaml build api
docker compose --env-file Backend/.local/compose.env -f compose.yaml up -d --no-build --no-deps --wait --wait-timeout 90 api

停止两个服务

保留数据库数据卷。不要使用 down -v 或删除 postgres_data 卷，这会删除账号数据。

docker compose --env-file Backend/.local/compose.env -f compose.yaml stop

只读健康检查

成功时返回 status: ready、database: connected。

curl --fail http://localhost:18080/health/ready

查看备份文件列表

ls -lh Backend/.local/backups/*.dump

只读查看备份目录内容

替换为实际 .dump 路径；这里只读取备份，不恢复数据。

db_backup_path='Backend/.local/backups/替换为实际备份文件.dump'
docker compose --env-file Backend/.local/compose.env -f compose.yaml exec -T db pg_restore --list < "$db_backup_path"

恢复到独立的新数据库

先修改备份路径，并选择尚不存在的数据库名称。这是操作示例，本次没有执行恢复，也没有修改玩家进度。

db_restore_name='sanguo_restore_20261011'
db_backup_path='Backend/.local/backups/替换为实际备份文件.dump'
test -f "$db_backup_path" && \
docker compose --env-file Backend/.local/compose.env -f compose.yaml exec -T db createdb -U sanguo "$db_restore_name" && \
docker compose --env-file Backend/.local/compose.env -f compose.yaml exec -T db pg_restore -U sanguo -d "$db_restore_name" --exit-on-error < "$db_backup_path"

只读检查独立恢复库

db_restore_name='sanguo_restore_20261011'
docker compose --env-file Backend/.local/compose.env -f compose.yaml exec -T db psql -U sanguo -d "$db_restore_name" -c "SELECT current_database(); SELECT count(*) AS public_tables FROM information_schema.tables WHERE table_schema = 'public';"