Skip to content
jiaopengziPublic

About

markdown 博客系统部署工具, 适用于自建博客。支持付费阅读,付费视频等会员内容分发。

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

blog-tool

博客系统部署工具,通过 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 安装脚本继续沿用原更新策略, 本次不改为锁版本安装.

快速开始

1. 获取工具

OSS (推荐)

curl -fsSL -o blog-tool.sh https://demo.jiaopengzi.com/sh/blog-tool.sh

GitHub

curl -fsSL -o blog-tool.sh https://raw.githubusercontent.com/jiaopengzi/blog-tool/main/dist/blog-tool.sh

2. 工具使用

sudo bash blog-tool.sh

工具下载好后直接使用如上命令执行即可看到命令面板。

image

3. 零交互一键安装

如果需要在全新服务器上跳过命令面板和确认提示, 可以使用 --auto 模式,推荐在自己没有域名内网使用:

sudo bash blog-tool.sh --auto

也可以直接下载、保存并立即执行, 省去手动下载后再运行的步骤。

OSS (推荐)

curl -fsSL -o blog-tool.sh https://demo.jiaopengzi.com/sh/blog-tool.sh && sudo bash blog-tool.sh --auto

GitHub

curl -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 数据库镜像。

4. 卸载当前安装

用户版支持通过 --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.Z Git tag 时,工作流会上传对应版本号的 OSS 文件,不会重新构建 dist/。

指定 tag 重建后端镜像

开发版提供 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.1

SERVER_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。

1. 构建并推送单镜像

按 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。

2. 从源码全量构建单镜像

需要验证指定前后端源码或重新编译既有版本时, 在 --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.1

vX.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

推送顺序如下:

  1. 仅在显式传入 --repo 时, 才推送到 REGISTRY_REMOTE_SERVER_PUBLIC/blog。
  2. 仅在显式传入 --tencent 时, 才推送到 REGISTRY_REMOTE_SERVER_TENCENT/blog。
  3. 仅在显式传入 --docker-hub 时, 才推送到 docker.io/jiaopengzi/blog。

当目标仓库凭据未配置时, 对应仓库推送会自动跳过, 不影响其它已显式选择的仓库。

3. 运行独立镜像

独立镜像约定只挂载一个总目录, 默认使用 HTTPS, 并在首次启动时自动生成 CA 证书与 HTTPS 证书。若第二次启动发现证书已存在, 则不会重复生成。

镜像会根据可见内存自动选择更保守的 ES、PostgreSQL、Nginx 参数。若是小内存机器, 建议在启动容器前, 直接在部署宿主机执行一次如下命令。

sudo sysctl vm.overcommit_memory=1

如需手动覆盖配置, 可在 docker run 时传入以下环境变量:

  • BLOG_MEMORY_PROFILE=small
  • BLOG_ES_JAVA_OPTS=-Xms384m -Xmx384m
  • BLOG_PG_SHARED_BUFFERS=64MB
  • BLOG_PG_MAX_CONNECTIONS=40

使用宿主机内网 IP 部署

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.crt

使用自定义证书和域名

sudo 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:latest

启动后状态校验

sudo 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。

获取指定版本工具

OSS (推荐)

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 也遵循同样的命名规则.

GitHub

curl -fsSL -o blog-tool.sh https://raw.githubusercontent.com/jiaopengzi/blog-tool/v1.4.1/dist/blog-tool.sh

许可证

MIT © 焦棚子

About

markdown 博客系统部署工具, 适用于自建博客。支持付费阅读,付费视频等会员内容分发。

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages