Docker

Docker 容器化部署

Docker 容器化部署

官方镜像已发布到 Docker Hub（pollybird/zhycms）、GitHub Container Registry（ghcr.io/pollybird/zhycms）和 阿里云 ACR（crpi-9u7ztjb0thx22k1a.cn-hangzhou.personal.cr.aliyuncs.com/pollybird/zhycms），当前版本 v3.1.3，开箱即用，无需本地构建。

一键安装（推荐）

项目提供交互式安装脚本，只需一条命令，按提示选择数据库、自动生成密钥，无需手动编辑任何文件：

`bash docker/install.sh`

脚本会引导你完成 5 步：选择数据库（MySQL/PostgreSQL）→ 自动生成安全密钥与密码 → 国内镜像加速（可选）→ Meilisearch 搜索引擎（可选）→ 端口与 Worker 数量。配置确认后自动生成 .env、拉取基础镜像、构建并启动服务。

脚本自动生成的 .env 包含随机密钥和密码，安全可靠。卸载时运行 bash docker/uninstall.sh，可选择保留或删除数据。

使用预构建镜像（最快）

直接拉取官方镜像（Docker Hub / GitHub GHCR / 阿里云 ACR 任选其一，国内推荐阿里云），无需本地构建：

`cp docker/.env.example .env
# 编辑 .env 修改 SECRET_KEY 和数据库密码

# MySQL 8.4（镜像 pollybird/zhycms:mysql）
docker compose -f docker-compose.mysql.yml up -d

# PostgreSQL 16（镜像 pollybird/zhycms:postgresql）
docker compose -f docker-compose.postgresql.yml up -d`

也可单独拉取镜像：

• Docker Hub：docker pull pollybird/zhycms:mysql（或 :postgresql / :latest / :v3.1.3）
• GitHub GHCR：docker pull ghcr.io/pollybird/zhycms:mysql（或 :postgresql / :latest / :v3.1.3）
• 阿里云 ACR（国内推荐）：docker pull crpi-9u7ztjb0thx22k1a.cn-hangzhou.personal.cr.aliyuncs.com/pollybird/zhycms:mysql（或 :postgresql / :latest / :v3.1.3）

三个 tag（mysql / postgresql / latest）指向同一镜像，内置 MySQL + PostgreSQL 驱动，通过 ZHYCMS_DB_URI 切换数据库。GHCR 镜像默认与 GitHub 账号关联，如需匿名拉取请到 GitHub Packages 页面将可见性改为 Public。

手动配置（进阶，本地构建）

如需本地构建或使用 MariaDB 方案，用通用编排文件：

`cp docker/.env.example .env
# 编辑 .env 修改密钥和数据库密码

docker compose --profile mysql up -d      # MySQL 方案
docker compose --profile mariadb up -d    # MariaDB 11.4 方案
docker compose --profile postgres up -d   # PostgreSQL 方案`

镜像特点

• 已发布到多镜像源：Docker Hub（pollybird/zhycms）、GitHub GHCR（ghcr.io/pollybird/zhycms）、阿里云 ACR（crpi-9u7ztjb0thx22k1a.cn-hangzhou.personal.cr.aliyuncs.com/pollybird/zhycms），均提供 mysql / postgresql / latest / v3.1.3 四个 tag（同一镜像，内置 MySQL + PostgreSQL 驱动，通过 ZHYCMS_DB_URI 切换）。
• 多阶段构建：builder 阶段编译依赖，runtime 阶段基于 python:3.12-slim，体积约 495MB。
• 非 root 运行：uid 1000 的 zhycms 用户，增强安全性。
• 自动初始化：entrypoint.sh 执行迁移 → 恢复演示图 → 编译 i18n → 启动 gunicorn。
• 健康检查：GET /healthz 返回数据库状态，豁免初始化拦截，供探针使用。

环境变量

变量	说明	必填
ZHYCMS_SECRET_KEY	Flask 会话密钥	✅
ZHYCMS_DB_URI	数据库 URI（compose 按 profile 自动注入）	✅
APT_MIRROR	构建期 apt 镜像源（如 mirrors.tuna.tsinghua.edu.cn）	❌
PIP_INDEX_URL	构建期 pip 镜像源	❌

裸机部署无需迁移到 Docker，v2.4.0 代码在裸机环境同样正常运行。