博客系统部署工具,通过 Docker 在 Debian Ubuntu 服务器上自动化部署完整的博客系统。
实际应用案例:https://jiaopengzi.com
- 操作系统: Debian 13 (Trixie)+ | Ubuntu 24.04+
- 架构: x86_64 (amd64)
- 权限: root 或具有 sudo 权限的用户
config/versions.sh 是本仓库依赖版本的唯一维护入口. 数据库、搜索组件、Node、nginx、Go、开发镜像及 single 基础系统版本均在此配置. PostgreSQL 主版本、Kibana 版本及镜像变体由基础版本派生, 不重复手填. ES、IK、Kibana 保持同版本, 升级前先确认 IK 对应版本已发布.
- 只修改需要升级的基础版本. Ubuntu 版本与发行代号、nginx 包修订号需配套核验.
- 升级 Node 时核验 Alpine 原生模块兼容性; C++ 运行库从同一 Node 镜像自动复制, 无需维护文件版本号.
- Cosign 保留动态查询最新发布的策略.
COSIGN_RELEASE_CHANNEL也可设为tags/vX.Y.Z, 查询指定 GitHub Release. - 执行
cd python && python3 -m unittest test_main.py test_versions.py -v检查配置与构建链路. 测试在临时目录生成三个发行版, 不访问现有业务、Docker 或仓库的发行产物. - 执行
bash build.sh重新生成发行脚本. 版本清单会先于内部配置合并, Docker 资产仍按原方式嵌入. - single 构建继续使用原有
--env-single和--build-single命令. 修改依赖后需先执行--env-single重建环境镜像, 不会自动替换已有镜像或升级运行中的服务.
两份 single 环境 Dockerfile 不再提供依赖版本默认值, 统一由构建入口传入.
绕过工具直接执行 docker build 时, 必须自行传入同名 ARG, 包括基础系统与兼容性参数.
已生成的发行脚本保留生成时的版本快照, 不会在线同步仓库配置.
此清单不控制前后端独立仓库 Dockerfile 的依赖、应用发布版本或现有 Compose 的实际运行版本. CI 的 Action、runner、任务容器版本仍在工作流内原生声明, Dockerfile syntax 版本仍保留原生声明. 宿主机 apt 软件与 Docker 安装脚本继续沿用原更新策略, 本次不改为锁版本安装.
curl -fsSL -o blog-tool.sh https://demo.jiaopengzi.com/sh/blog-tool.shcurl -fsSL -o blog-tool.sh https://raw.githubusercontent.com/jiaopengzi/blog-tool/main/dist/blog-tool.shsudo bash blog-tool.sh工具下载好后直接使用如上命令执行即可看到命令面板。
如果需要在全新服务器上跳过命令面板和确认提示, 可以使用 --auto 模式,推荐在自己没有域名内网使用:
sudo bash blog-tool.sh --auto也可以直接下载、保存并立即执行, 省去手动下载后再运行的步骤。
curl -fsSL -o blog-tool.sh https://demo.jiaopengzi.com/sh/blog-tool.sh && sudo bash blog-tool.sh --autocurl -fsSL -o blog-tool.sh https://raw.githubusercontent.com/jiaopengzi/blog-tool/main/dist/blog-tool.sh && sudo bash blog-tool.sh --auto如果需要传入可选参数, 将参数追加到 --auto 后即可:
curl -fsSL -o blog-tool.sh https://demo.jiaopengzi.com/sh/blog-tool.sh && sudo bash blog-tool.sh --auto --domain=example.com --project_name=blog-server--auto 会自动接受免责声明, 安装基础依赖和 Docker, 拉取生产镜像, 初始化数据库, 并安装 blog-server 与 blog-client。如果当前机器已经安装 Docker, 脚本会直接退出, 避免覆盖已有 Docker 环境。
零交互完整示例 推荐自备域名和证书首次安装使用,先下载工具再执行如下零交互脚本(注意将参数内容换成自己的实际的内容):
sudo bash blog-tool.sh --auto \
--domain=example.com \
--project_name=blog-server \
--public_ip=1.2.3.4 \
--cert=/your/path/cert.pem \
--cert_key=/your/path/cert.key \
--admin_username=admin \
--admin_email=admin@example.com \
--admin_password='Password123'参数说明:
| 参数 | 是否必填 | 说明 |
|---|---|---|
--domain |
否 | 访问域名, 不要带 http:// 或 https:// |
--project_name |
否 | 项目名称, 仅允许字母, 数字, 下划线和短横线 |
--public_ip |
否 | 当前服务器公网 IPv4 地址 |
--cert |
否 | nginx HTTPS 证书文件路径, 提供时必须同时提供 --cert_key |
--cert_key |
否 | nginx HTTPS 私钥文件路径, 提供时必须同时提供 --cert |
--admin_username |
否 | 管理员用户名, 提供任一 --admin_* 参数时三项都必须提供 |
--admin_email |
否 | 管理员邮箱, 提供任一 --admin_* 参数时三项都必须提供 |
--admin_password |
否 | 管理员密码, 提供任一 --admin_* 参数时三项都必须提供 |
说明:
--domain、--project_name、--public_ip不传时, 脚本会优先读取blog_tool_env中已有配置; 没有配置文件时使用默认值继续安装, 不会进入交互输入。--cert和--cert_key都不传时, 脚本跳过 nginx 证书复制; 只传其中一个会报错退出。--admin_username、--admin_email、--admin_password都不传时, 脚本跳过管理员自动注册; 只传其中任意一个会报错退出。- 管理员用户名必须是 6-20 位小写字母或数字; 管理员密码必须是 6-64 位, 且包含大写字母, 小写字母和数字。
--auto拉取生产镜像时默认包含 PostgreSQL、Redis、Elasticsearch 数据库镜像。
用户版支持通过 --uninstall 卸载当前 blog-tool.sh 安装的项目:
sudo bash blog-tool.sh --uninstall执行后脚本会先逐项询问您是否需要执行以下清理动作, 再按您的选择依次执行:
- 停止并删除当前项目容器
- 删除当前项目涉及的 Docker 镜像
- 删除当前项目 volume 数据目录
- 卸载 Docker 软件
- 删除
blog-tool日志文件
说明:
--uninstall仅支持用户版blog-tool.sh, 不支持blog-tool-dev.sh和blog-tool-billing-center.sh。- 删除 volume 时会移除当前工具的数据根目录, 因此会一并删除数据库数据、服务配置、证书、docker compose 文件和
blog_tool_env状态文件。 - 为避免镜像删除失败, 卸载流程会额外清理本工具可能残留的临时容器和项目网络。
- 卸载完成后, 脚本会提示当前脚本文件路径; 脚本文件本身不会自删, 需要您手动删除。
| 组件 | 技术 | 说明 |
|---|---|---|
| 后端 | blog-server (Go) | Docker 容器化部署 |
| 前端 | blog-client (Nginx) | Docker 容器化部署 |
| 数据库 | PostgreSQL 18.3 | 支持自定义配置 |
| 缓存 | Redis 8.6.2 | 支持单节点和集群模式 |
| 搜索引擎 | Elasticsearch 9.3.3 | 支持多节点集群、IK 分词器、Kibana |
| 证书 | 自签名 CA + SSL/TLS | 自动生成 |
项目通过 build.sh 将模块化脚本合并为单文件发行版:
| 版本 | 文件 | 说明 |
|---|---|---|
| 用户版 | blog-tool.sh |
博客部署,面向最终用户 |
| 计费中心版 | blog-tool-billing-center.sh |
计费中心部署 |
| 开发版 | blog-tool-dev.sh |
含全部功能,面向开发者 |
发布策略:
- 所有发行版脚本均在本地执行
bash build.sh后生成,并提交到仓库中的dist/目录。 - GitHub Actions 工作流 push-oss.yaml 不再负责远端构建,只负责把仓库中已有的
dist/产物推送到 OSS。 - GitHub Actions 工作流 sync_gitee.yaml 只负责将 GitHub 仓库的
main分支和 Git tags 同步到 Gitee 镜像仓库。 - 向
main分支推送且dist/有变更时,工作流会覆盖上传 OSS latest 文件。 - 推送
vX.Y.ZGit tag 时,工作流会上传对应版本号的 OSS 文件,不会重新构建dist/。
开发版提供 docker_build_push_server_by_tag,用于恢复或重建已发布的后端版本。GitLab tag pipeline 中,
该命令优先复用 $CI_PROJECT_DIR 的精确 checkout;本地执行时才将指定的 blog-server-dev Git tag 浅克隆到
独立的临时构建目录。它直接使用标准 Dockerfile 做全量构建,然后强制覆盖私有仓库、Docker Hub 和腾讯云仓库
中的同名版本 tag。它不会构建 blog-server:golang 环境镜像,也不会更新三个仓库的 latest tag。
在 GitLab tag pipeline 中可使用如下命令,其中 SIGN_PRIVATE_KEY、COSIGN_PRIVATE_KEY 是 GitLab 的
File 类型变量,其他密钥和凭据应配置为受保护的 CI/CD 变量:
sudo SIGN_PRIVATE_KEY="$SIGN_PRIVATE_KEY" \
COSIGN_PRIVATE_KEY="$COSIGN_PRIVATE_KEY" \
COSIGN_PRIVATE_KEY_PWD="$COSIGN_PRIVATE_KEY_PWD" \
SERVER_TAG_BUILD_SOURCE_DIR="$CI_PROJECT_DIR" \
REGISTRY_REMOTE_SERVER="$REGISTRY_REMOTE_SERVER" \
REGISTRY_USER_NAME="$REGISTRY_USER_NAME" \
REGISTRY_PASSWORD="$REGISTRY_PASSWORD" \
DOCKER_HUB_TOKEN="$DOCKER_HUB_TOKEN" \
REGISTRY_USER_NAME_TENCENT="$REGISTRY_USER_NAME_TENCENT" \
REGISTRY_PASSWORD_TENCENT="$REGISTRY_PASSWORD_TENCENT" \
bash /home/jiaopengzi/blog-tool-dev.sh docker_build_push_server_by_tag "$CI_COMMIT_TAG"本地或手动流水线也可显式传入版本,例如:
sudo bash blog-tool-dev.sh docker_build_push_server_by_tag v1.0.1SERVER_TAG_BUILD_SOURCE_DIR 应在 GitLab 命令中显式传入,因为 sudo 默认不会保留 CI_PROJECT_DIR。GitLab
tag pipeline 无需 GIT_LOCAL;本地或非 tag pipeline 执行时才需要它来克隆指定源码。DOCKER_HUB_OWNER 和
REGISTRY_REMOTE_SERVER_TENCENT 已有工具默认值,但可按部署环境覆盖。
开发版 --build-single 命令, 用于将 blog-client、blog-server-dev、PostgreSQL、Redis、Elasticsearch 打包为一个独立镜像 blog。
按 env -> build -> push 分阶段执行:
sudo bash blog-tool-dev.sh --env-single
sudo bash blog-tool-dev.sh --build-single --server v1.0.0 --client v1.0.0
sudo bash blog-tool-dev.sh --push-single --repo--build-single 需要显式传入 --server 与 --client。脚本会直接拉取
jiaopengzi/blog-server:<version> 和 jiaopengzi/blog-client:<version> 参与装配, 然后基于这两个版本自动计算
single 版本, 并保存给后续 --push-single 使用。构建结束后会自动清理本地临时拉取的这两个前后端镜像 tag。
需要验证指定前后端源码或重新编译既有版本时, 在 --build-single 后增加 --source-code。该模式会在
single 构建上下文中创建隔离浅克隆, 不会切换或修改现有的 blog-client、blog-server-dev 开发工作区。
后端完整 Dockerfile 使用 BuildKit sign_key secret 对二进制签名, 因此必须传入可读取的
blog-server 产物签名私钥 SIGN_PRIVATE_KEY, 与 GitLab CI 的构建命令保持一致. 此私钥不同于
用于镜像签名的 COSIGN_PRIVATE_KEY, 不可传入加密 cosign 密钥文件:
sudo SIGN_PRIVATE_KEY=/absolute/path/to/sign_key.pem \
bash blog-tool-dev.sh --build-single --source-code --server v1.0.1 --client v1.0.1vX.Y.Z 会精确检出同名 Git tag; latest 会检出默认分支的最新提交:
sudo SIGN_PRIVATE_KEY=/absolute/path/to/sign_key.pem \
bash blog-tool-dev.sh --build-single --source-code --server latest --client latest源码模式对前后端均使用仓库根目录的完整 Dockerfile 和 --no-cache 全量构建。源码临时目录及前后端临时
输入镜像会在 single 装配结束后清理; v1.0.1 的 SPA 与 Nuxt SSR 客户端产物都可装配为同一个 single 镜像。
注意 blog-server 1.0.1 使用的是 go 1.26.5 最新的已经升级到了 1.27.1 编译上会有不兼容
--push-single 需要显式指定至少一个远端仓库, 支持按需组合 --repo、--tencent、--docker-hub:
sudo bash blog-tool-dev.sh --push-single --repo
sudo bash blog-tool-dev.sh --push-single --tencent
sudo bash blog-tool-dev.sh --push-single --docker-hub
sudo bash blog-tool-dev.sh --push-single --repo --tencent --docker-hub推送顺序如下:
- 仅在显式传入
--repo时, 才推送到REGISTRY_REMOTE_SERVER_PUBLIC/blog。 - 仅在显式传入
--tencent时, 才推送到REGISTRY_REMOTE_SERVER_TENCENT/blog。 - 仅在显式传入
--docker-hub时, 才推送到docker.io/jiaopengzi/blog。
当目标仓库凭据未配置时, 对应仓库推送会自动跳过, 不影响其它已显式选择的仓库。
独立镜像约定只挂载一个总目录, 默认使用 HTTPS, 并在首次启动时自动生成 CA 证书与 HTTPS 证书。若第二次启动发现证书已存在, 则不会重复生成。
镜像会根据可见内存自动选择更保守的 ES、PostgreSQL、Nginx 参数。若是小内存机器, 建议在启动容器前, 直接在部署宿主机执行一次如下命令。
sudo sysctl vm.overcommit_memory=1如需手动覆盖配置, 可在 docker run 时传入以下环境变量:
BLOG_MEMORY_PROFILE=smallBLOG_ES_JAVA_OPTS=-Xms384m -Xmx384mBLOG_PG_SHARED_BUFFERS=64MBBLOG_PG_MAX_CONNECTIONS=40
HOST_IP="$(hostname -I | awk '{print $1}')" && sudo docker run -d \
--name blog \
-p 443:443 \
-v /data/blog:/data \
-e BLOG_PUBLIC_HOST="$HOST_IP" \
jiaopengzi/blog:latest首次启动后, 可从宿主机挂载目录导出 CA 证书:
/data/blog/certs/internal-ca/ca.crtsudo docker run -d \
--name blog \
-p 443:443 \
-v /data/blog:/data \
-v /your/path/cert.pem:/data/blog-client/nginx/ssl/cert.pem \
-v /your/path/cert.key:/data/blog-client/nginx/ssl/cert.key \
-e BLOG_PUBLIC_HOST=blog.example.com \
jiaopengzi/blog:latestsudo docker ps -a | grep blog
sudo docker logs blog同时使用如下 curl 校验是否通畅
在部署机执行 curl -vk https://127.0.0.1:443,先确认宿主机本地 HTTPS 是否通。
在外部机器执行 curl -vk https://blog.example.com/,再看是 DNS、链路还是证书链问题。
如果您更习惯先把证书整理到数据目录, 也可以预先放到 /data/blog/blog-client/nginx/ssl/cert.pem 和 /data/blog/blog-client/nginx/ssl/cert.key, 再只挂载 -v /data/blog:/data 启动。
| 变量 | 默认值 | 说明 |
|---|---|---|
BLOG_PUBLIC_HOST |
localhost |
对外访问域名或 IP, 用于生成默认证书和后端 host |
BLOG_HTTPS_PORT |
443 |
容器内 HTTPS 监听端口 |
BLOG_PG_PORT |
15432 |
容器内 PostgreSQL 监听端口 |
BLOG_REDIS_PORT |
16379 |
容器内 Redis 监听端口 |
BLOG_ES_PORT |
19200 |
容器内 Elasticsearch HTTPS 监听端口 |
- 仅执行
sudo docker run -d blog:latest不会自动发布宿主机端口, 仍需显式添加-p 443:443, 否则无法从宿主机或局域网访问。 - 数据库默认不占用容器内常见端口, 如果需要对外连接数据库, 请自行增加端口映射, 例如
-p 5432:15432。 - Elasticsearch 内置 IK 分词器, 默认保留空的
my.dic, 可在挂载目录中按需维护。
├── build.sh # 构建脚本
├── config/ # 配置文件
│ ├── internal.sh # 内部配置 (不可修改)
│ ├── user.sh # 用户配置
│ └── dev.sh # 开发配置
├── options/ # 菜单选项定义
├── system/ # 系统工具 (apt、软件安装、SSH)
├── docker/ # Docker 安装与管理
├── db/ # 数据库 (PostgreSQL、Redis、ES)
├── server/ # 后端服务部署
├── client/ # 前端服务部署
├── billing-center/ # 计费中心部署
└── utils/ # 工具函数集合
项目遵循语义化版本控制,版本号格式为 vX.Y.Z。
curl -fsSL -o blog-tool.sh https://demo.jiaopengzi.com/sh/blog-tool-v1.4.1.sh说明:
https://demo.jiaopengzi.com/sh/blog-tool.sh始终指向主分支最新构建产物.https://demo.jiaopengzi.com/sh/blog-tool-vX.Y.Z.sh仅在推送对应 Git tag 后生成.blog-tool-dev和blog-tool-billing-center也遵循同样的命名规则.
curl -fsSL -o blog-tool.sh https://raw.githubusercontent.com/jiaopengzi/blog-tool/v1.4.1/dist/blog-tool.shMIT © 焦棚子