docker

README.md

@@ -94,6 +94,59 @@ npm start
 
 本地开发无需额外配置，首次运行会自动创建 `data/exam.sqlite` 和完整关系型数据库结构，但不会导入学校、考生、考试或报名测试数据。首次建库只写入系统基础配置和一个超级管理员；账号、密码和显示名可通过 `INITIAL_ADMIN_USERNAME`、`INITIAL_ADMIN_PASSWORD`、`INITIAL_ADMIN_DISPLAY_NAME` 设置。当前数据库结构版本为 v17；v16 数据库会自动增加 TOTP 字段，低于 v15 的开发库会提示重建。
 
+### Docker
+
+项目根目录包含生产镜像和 Docker Compose 配置。默认使用 SQLite，数据库保存在命名卷 `exam-information-data` 中，因此重建容器不会丢失数据。
+
+先创建容器环境文件，并将其中的 TOTP 主密钥和初始管理员密码替换为安全随机值：
+
+```powershell
+Copy-Item .env.docker.example .env.docker
+```
+
+然后构建并启动：
+
+```powershell
+docker compose up --build --detach
+```
+
+启动完成后访问 <http://127.0.0.1:4173>。查看状态和日志可运行：
+
+```powershell
+docker compose ps
+docker compose logs --follow app
+```
+
+停止服务使用 `docker compose down`；该命令会保留数据库卷。只有明确需要删除全部 SQLite 数据时才使用 `docker compose down --volumes`。
+
+也可以只构建镜像：
+
+```powershell
+docker build --tag hengzhun-exam-system:local .
+```
+
+镜像默认监听 `0.0.0.0:4173`，以非 root 用户运行，并通过 `/api/public/home` 执行健康检查。需要连接 MySQL 或 Redis 时，用运行环境变量覆盖 `DATABASE_CLIENT`、`DATABASE_URL`/`MYSQL_*`、`REDIS_URL`；此时 SQLite 数据卷可以移除。
+
+#### Gitea Actions 自动发布到 Docker Hub
+
+工作流位于 `.gitea/workflows/docker-publish.yml`。它会先安装依赖并运行测试，然后构建 `linux/amd64`、`linux/arm64` 双架构镜像并推送到 Docker Hub。
+
+使用前需要完成以下配置：
+
+1. 在 Docker Hub 创建目标仓库，并创建具有该仓库 Read & Write 权限的访问令牌。
+2. 在 Gitea 仓库的 Actions Variables 中添加 `DOCKERHUB_IMAGE`，值为不带 registry 和 tag 的完整镜像名，例如 `yourname/exam-information-system`。
+3. 在 Gitea 仓库的 Actions Secrets 中添加 `DOCKERHUB_USERNAME` 和 `DOCKERHUB_TOKEN`。前者填写 Docker Hub 用户名，后者填写访问令牌，不要填写账户密码。
+4. 确保 Gitea Actions 已启用，并且 `ubuntu-latest` Runner 能访问 Docker daemon、GitHub 和 Docker Hub。双架构构建还需要 Runner 允许 QEMU 注册步骤运行。
+
+推送到 `master` 后会发布 `latest` 和 `sha-<短提交号>`；推送形如 `v1.2.3` 的 Git 标签后会发布 `1.2.3`、`1.2` 和对应的提交标签。例如：
+
+```powershell
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+工作流也支持从 Gitea Actions 页面手动运行。构建缓存保存为同一 Docker Hub 仓库中的 `buildcache` 标签，以加快后续构建。
+
 需要清空并重建空业务库时运行 `npm run reset-db`。需要测试数据时再手动运行 `npm run seed-test-data`；导入脚本会读取项目根目录的 `.env`，并根据 `DATABASE_CLIENT` 选择 SQLite 或 MySQL。它会生成 4 所学校、360 名批量考生及 360 条不同状态的报名数据，并明确不生成考场编排计划和准考证。省市区县下拉数据位于 `src/data/china-regions.mjs`，当前版本为国家地名信息库截至 2025-12-31 的三级快照，并补入和康县（653228）与和安县（653229）；从新版 CSV 更新时可运行 `node scripts/build-regions.mjs <CSV路径> src/data/china-regions.mjs`。
 
 ## 数据库配置