部署指南：Docker 一键部署与手动部署

本项目由四个服务组成：MySQL 数据库、FastAPI 接口、Next.js 前台和 Umi 管理后台。推荐使用 Docker Compose 一键部署；不使用 Docker 时，也可以分别启动三个应用并连接已有 MySQL。

一、Docker 一键部署

1. 环境要求

• Windows：Docker Desktop
• Linux：Docker Engine 与 Docker Compose Plugin
• 建议至少 2 核 CPU、4 GB 内存和 10 GB 可用磁盘

确认 Docker 已启动：

docker version
docker compose version

2. 一条命令启动

在项目根目录执行：

docker compose up -d --build

Compose 会自动构建并启动：

首次创建 MySQL 数据卷时，系统会依次导入：

1. api-fastapi/sql/schema.sql：数据库结构。
2. api-fastapi/sql/current-data.sql：当前公开文章、分类、标签、站点配置和引用图片。

初始化脚本只在空数据卷首次启动时执行。已有 mysql_data 数据卷不会被重复覆盖。

3. 查看状态和日志

docker compose ps
docker compose logs -f

只查看某个服务：

docker compose logs -f api
docker compose logs -f blog
docker compose logs -f admin
docker compose logs -f mysql

停止服务但保留数据库：

docker compose down

重新启动：

docker compose up -d

不要在有正式数据时执行 docker compose down -v，-v 会删除 MySQL 数据卷。

二、生产环境配置

本地默认值用于快速体验，不适合直接暴露到公网。生产部署前先复制模板：

cp .env.docker.example .env

Windows PowerShell：

Copy-Item .env.docker.example .env

至少修改以下项目：

APP_ENV=production
DB_PASSWORD=请替换为高强度数据库密码
MYSQL_ROOT_PASSWORD=请替换为高强度Root密码
JWT_SECRET=请替换为至少32字符的随机密钥
ADMIN_PASSWORD=请替换为至少12位的后台初始密码

NEXT_PUBLIC_API_ORIGIN=https://api.example.com
UMI_APP_API_ORIGIN=https://api.example.com
UMI_APP_BLOG_ORIGIN=https://www.example.com
BLOG_ORIGIN=https://www.example.com
ADMIN_ORIGIN=https://admin.example.com

域名变量说明：

• NEXT_PUBLIC_API_ORIGIN：前台浏览器加载图片和 API 资源时访问的公网地址。
• UMI_APP_API_ORIGIN：管理后台访问 API 的公网地址。
• UMI_APP_BLOG_ORIGIN：管理后台“查看前台”按钮的地址。
• BLOG_ORIGIN、ADMIN_ORIGIN：FastAPI CORS 允许的前后台来源。
• API_INTERNAL_ORIGIN：Compose 已固定为容器内部的 http://api:9105，通常无需修改。

修改浏览器端地址后需要重新构建前后台：

docker compose up -d --build

建议使用 Nginx、Caddy、Traefik 或云平台网关配置 HTTPS，并分别将域名代理到 9102、9180 和 9105。

三、数据持久化与文章更新

MySQL 数据保存在 Docker volume next-umi-fastapi_mysql_data。文章、配置和上传文件都在数据库中，其中上传文件二进制保存在 file_store.file_data。

代码升级不会自动覆盖正在运行的文章。更新程序时执行：

git pull
docker compose up -d --build

仓库中的 current-data.sql 仅用于全新数据卷初始化。线上文章应通过管理后台编辑，或先备份数据库再执行迁移。

备份数据库：

docker compose exec mysql sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --hex-blob "$MYSQL_DATABASE"' > backup.sql

恢复前应停止写入并确认备份文件完整。不要把包含真实密码、用户隐私或私有 Token 的数据库备份提交到公开仓库。

四、部署后检查

依次确认：

1. http://localhost:9105/health 返回 ok: true。
2. 前台首页、文章详情、分类、标签、归档和个人页可以打开。
3. 管理后台可以登录，默认体验账号为 admin / 123456；生产环境必须通过 .env 修改。
4. 后台可以新建草稿、发布文章、设置分类标签和置顶状态。
5. 图片可以上传，文章封面、头像、Logo 和 favicon 可以正常访问。
6. 执行 docker compose restart 后文章与图片仍然存在。

容器健康状态：

docker compose ps

如果 API 未启动，优先检查 MySQL 是否健康、数据库密码是否一致，以及 JWT_SECRET 是否至少 32 个字符。

五、手动部署

1. MySQL

创建 hzj_blog_v2 数据库，依次导入：

mysql -u root -p hzj_blog_v2 < api-fastapi/sql/schema.sql
mysql -u root -p hzj_blog_v2 < api-fastapi/sql/current-data.sql

如果连接的是已有数据库，不要再次导入 current-data.sql。

2. FastAPI

cd api-fastapi
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 9105

Linux 将虚拟环境路径改为 .venv/bin/python。

3. Next.js 前台

cd blog
npm ci
npm run build
npm run start

4. Umi 管理后台

cd admin-umi
npm ci
npm run build

将 admin-umi/dist 交给 Nginx 等静态服务器，并为 Browser History 配置回退到 index.html。

六、本地开发脚本

已经安装本地依赖并准备好 MySQL 后，可以在项目根目录执行：

.\scripts\start-dev.ps1
.\scripts\health-check.ps1
.\scripts\stop-dev.ps1

开发脚本与 Docker Compose 使用相同的默认端口，因此不要同时启动两套服务。