跳转到主要内容

Docker 部署

用 Docker 镜像在生产环境部署

本节假定不使用 CDN 部署，且已通过宝塔面板正确安装 Docker。

低配置服务器不推荐在服务器中部署，无论是通过源码部署还是Docker 部署，因为它在构建服务端时会占满 CPU 和内存，会导致服务器卡死。

准备工作

在服务器中执行：

Bashgit clone --recurse-submodules https://github.com/imqi1-github/imqi1-cms.git
cd imqi1-cms
cp .env.example .env

修改 .env 中的配置信息，示例：

EnvDB_PASSWORD="改成强密码"          # PostgreSQL 应用用户密码（compose 用它建库并传给 POSTGRES_PASSWORD）
DB_NAME="imqi1-cms"           # 库名，可自定义；compose 建库与导入 SQL 都用它
DB_USER="nodejs"                 # 应用连接用户；PG 单用户即超级用户，建议沿用非 postgres 的命名
DEPLOY_PORT=3000                   # 宿主对外端口，按需修改

还可以设置以下可选变量，具体说明见 环境变量 章节。

EnvUPLOADS_DIR=""                 # 上传目录宿主路径；默认项目根 uploads/，本地可见
LOGS_DIR=""                    # 日志目录；裸机默认 ./logs，Docker 部署为挂载日志的宿主路径（默认项目根 logs/）
AMAP_KEY=""                    # 高德地图 Key（旅行足迹地图功能）
AMAP_SECURITY_CODE=""          # 高德 JS API 安全密钥
SSR_INTERNAL_REQUEST_SECRET="" # SSR 内部请求密钥（建议随机长串）
MINI_API_SECRET=""             # 小程序 API 签名密钥

Redis 不在 .env 中配置，所选 compose 文件决定默认是否启用 Redis，连接参数已在 compose 内固定为服务名 redis。如需连接其他 Redis，请参见下文「指定 Redis 参数」。

修改 site.config.ts 中的预定义变量，_cdnUrl 设为空，_url 设为你将来的生产域名（带协议头）。

启动 Docker Compose

在项目根目录启动终端，执行：

Bash# 带 Redis：构建镜像 + 后台启动 app / postgres / redis
docker compose --env-file .env -f docker/docker-compose.yml up -d --build

# 不带 Redis：仅 app / postgres
docker compose --env-file .env -f docker/docker-compose.noredis.yml up -d --build

执行成功：

在宝塔面板中也可以看到编排成功的容器和 Compose。

镜像加速

服务器在国内拉取基础镜像较慢或超时，可以给 Docker 守护进程配置镜像源。编辑 /etc/docker/daemon.json（不存在则新建）：

JSON{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

重载配置使其生效：

Bashsystemctl reload docker

docker.m.daocloud.io 是我实际验证过可用的源，也可以按网络情况换成其他镜像源；Windows 与 macOS 的 Docker Desktop 在 Settings → Docker Engine 的 JSON 编辑器中修改，点击 Apply & Restart。

日志目录

九类运行日志由 compose 挂载到项目根的 logs/ 目录，每类别一个子目录、按天一个文件，在宿主机上可以直接查看，宿主路径可用 .env 的 LOGS_DIR 修改。日志的分类含义、大小切分与保留清理见 日志系统。

Linux 服务器上若 logs/ 目录属主不是容器内的运行用户（uid 1000），先执行 mkdir -p logs && chown 1000:1000 logs，否则文件日志不会写入，只剩容器终端输出。

指定 Redis 参数

带 Redis 的版本默认连接 compose 中的 redis 服务（redis:6379、DB 0、无鉴权），通常无需修改。如需使用其他 Redis，请在构建命令中通过 --build-arg 覆盖，不要修改 site.config.ts，也不要写入 .env：

Bashdocker compose --env-file .env -f docker/docker-compose.yml build --build-arg REDIS_HOST=10.0.0.5 --build-arg REDIS_PORT=6379 --build-arg REDIS_DB=1

可覆盖的变量包括 REDIS_ENABLED、REDIS_HOST、REDIS_PORT、REDIS_DB 四项，不支持密码。当前 redis 容器仅在 compose 内网可访问，未启用鉴权。这些值会在构建时写入产物，修改后需先使用 build 重新构建，再执行 up；不能使用 up --build，因为该命令不接受 --build-arg。

配置域名

在宝塔面板中，点击【Docker】→【网站】→【创建】→【反向代理】，填写相关信息。

保存并配置 SSL 证书后，即可访问站点。

升级项目

当源码发生更新，例如自行修改源码或获取新的更新包时，重新执行上述步骤完成构建即可，其余步骤不变。

重新构建/升级前，请先在后台备份数据：
常规的 docker compose ... up -d --build 只重建应用镜像，不会动 PostgreSQL 数据卷，数据是安全的。但在以下场景数据可能丢失或不兼容，务必先备份：

  • 需要执行 docker compose ... down -v（会删除数据卷、清空所有数据）；
  • 迁移服务器、更换数据库；
  • 版本升级涉及数据表结构变更。

备份方式（推荐）：登录后台 →「数据备份与恢复」→「导出数据」，下载全站数据 JSON 备份；升级完成后在同一页面「导入数据」即可恢复。（该功能不含 users/sessions 表，登录态与管理员账户不受影响。）

也可以直接对数据库做整库 SQL 级备份（用户名、库名换成你 .env 里的 DB_USER / DB_NAME）：

Bashdocker compose --env-file .env -f docker/docker-compose.yml exec postgres pg_dump -U nodejs imqi1-cms > backup.sql