okr-performance/docs/docker-deployment.md

Docker 部署与升级

默认镜像名称为 emoon-okr:latest。

数据持久化约定

SQLite 数据库不进入镜像，始终保存在宿主机：

宿主机 ./data/okr-performance.db
              ↕ bind mount
容器   /app/data/okr-performance.db

容器内 /app/data/backups 同样对应宿主机 ./data/backups。删除镜像、重建容器不会删除数据库；删除宿主机 ./data 会永久删除业务数据。

首次启动

cp .env.example .env
# 修改 .env 中的 JWT 密钥、管理员密码和访问域名
mkdir -p data
docker compose up -d --build
docker compose logs -f okr-performance

启动脚本会确认 /app/data 存在且可写。okr-performance.db 不存在时，Spring Boot 自动创建表结构、执行数据库迁移并初始化基础数据。

版本升级

建议升级前先备份，再重建镜像和容器：

mkdir -p data/backups
sqlite3 data/okr-performance.db ".backup 'data/backups/manual-before-upgrade.db'"
docker compose build --pull
docker compose up -d --force-recreate --remove-orphans
docker compose logs -f okr-performance

升级过程只替换镜像和容器，./data 继续挂载到新容器。应用启动后会在原数据库上执行尚未执行的增量迁移。

不要在升级脚本中加入 rm -rf data，也不要把数据库复制到 Dockerfile 或镜像中。

docker compose down -v 不会删除这里的宿主机 ./data 绑定目录，但仍建议生产环境只执行上面的升级命令，避免误操作其他 Docker 资源。

恢复备份

恢复前先停止服务，避免 SQLite 仍有写入：

docker compose stop okr-performance
cp data/backups/manual-before-upgrade.db data/okr-performance.db
rm -f data/okr-performance.db-wal data/okr-performance.db-shm
docker compose up -d

常用检查

docker compose ps
docker compose logs --tail=200 okr-performance
sqlite3 data/okr-performance.db "PRAGMA integrity_check;"

启动时报 JWT WeakKeyException

这表示容器收到的 APP_JWT_SECRET 为空或不足 32 字符，和 SQLite 数据无关。先确认项目根目录存在 .env：

cp .env.example .env
# 将全部 CHANGE_ME 替换为真实值
docker compose config
docker compose up -d --build

新版 Compose 配置会在 .env 缺失或关键变量为空时直接终止，并指出需要配置的变量；不会再把空密钥传给 Spring Boot 后才抛出深层 JWT 异常。