gocron Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上用 Docker Compose 把 gocron 0.14.1 从零部署到可日常使用的状态——官方分发件选型、数据持久化布局、启动验证、升级回滚与常见故障一次讲清。全部命令与回显均在 Ubuntu 22.04（x86_64）实机环境实测通过，实测版本 v0.14.1（2026-10-23 发布，查询日期 2026-10-30）。

一、环境信息

本文实测部署所用的环境基线如下，读者复现时保持相近版本即可：

• 操作系统：Ubuntu 22.04 LTS（x86_64），内核 5.15+
• Compose 工具：Docker Compose v2（docker compose 子命令形态）
• gocron 版本：v0.14.1（官方分发渠道 ghcr.io/flohoss/gocron，OCI 标准标签 org.opencontainers.image.ref.name: v0.14.1）
• 服务端口：容器内 8156，宿主映射 8128（8128–8152 段内任选未占用端口均可）
• 数据目录：/opt/gocron/config（配置文件 + SQLite 运行库）、/opt/gocron/data（任务数据）
• 时区：Asia/Shanghai
• 资源占用：单二进制 + SQLite，空载内存占用在几十 MB 量级，1C1G 虚拟机即可承载

二、镜像选型说明

gocron 的官方分发渠道是 GitHub Container Registry 上的 ghcr.io/flohoss/gocron，由作者 flohoss 维护并随版本发布同步更新，渠道信息来自项目官方发布说明（查询日期 2026-10-30）。

选型要点：

1. 只用官方渠道：ghcr.io/flohoss/gocron 是项目唯一官方分发渠道，README 与发布说明均指向它；第三方转存镜像不保证构建来源。
2. tag 策略：latest 跟随最新稳定版（实测拉取时即 v0.14.1，OCI 标签 org.opencontainers.image.ref.name: v0.14.1 可验证）。生产环境建议固定具体版本 tag（如 ghcr.io/flohoss/gocron:v0.14.1），升级时再显式变更，避免 latest 自动漂移引入不兼容变更。
3. 形态说明：分发件内是单个 gocron 二进制 + Vue.js 构建的静态前端，入口 dumb-init -- /app/gocron，工作目录 /app；自带 cron 调度器与 SQLite 存储，无需外部数据库分发件。
4. 架构支持：官方分发件覆盖 linux/amd64 与 linux/arm64，ARM 设备（如树莓派、国产 ARM 小主机）同样可部署。

⚠️ 注意：社区里另有两个同名 Go 调度库（go-co-op/gocron、jasonlvhit/gocron），它们是嵌入代码用的库而非服务，不存在 Web 面板。拉取分发件认准 ghcr.io/flohoss/ 前缀。

三、前置条件

部署前确认以下条件逐项满足：

1. 服务器已安装 Docker Engine 与 Compose v2 插件，验证命令与实测回显：

docker --version && docker compose version

Docker version 27.3.1, build 12243a0
Docker Compose version v2.29.7

2. 端口未占用：确认宿主侧要映射的端口（本文用 8128）空闲：

ss -ltn | grep 8128 || echo "port 8128 free"

port 8128 free

3. 目录已创建并规划好持久化布局：

mkdir -p /opt/gocron/config /opt/gocron/data

4. 网络可达官方分发渠道：服务器直连 ghcr.io 慢或失败时，为 Docker 配置 HTTP 代理（/etc/docker/daemon.json 的 proxies 段或 systemd 环境变量 HTTPS_PROXY），本文实测环境即通过 http://192.168.1.62:7897 代理完成拉取；亦可改用国内转存渠道（如 docker.1ms.run 前缀）拉取后重新打 tag。

四、部署步骤

完整编排文件与启动流程如下，全部步骤在实机一次跑通。

第 1 步：编写 /opt/gocron/docker-compose.yml：

name: gocron-0.14.1-stack

services:
  gocron:
    image: ghcr.io/flohoss/gocron:latest
    container_name: gocron-0.14.1-app
    hostname: gocron
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    ports:
      - "8128:8156"
    volumes:
      - ./config:/app/config
      - ./data:/app/data

逐项说明：

• name: gocron-0.14.1-stack：显式指定 Compose 项目名，多套环境并存时避免项目名冲突导致误删；
• restart: unless-stopped：服务器重启后自动拉起（手动停止的不拉起）；
• TZ=Asia/Shanghai：分发件内进程时区，影响日志时间戳显示；
• 8128:8156：宿主 8128 映射到 gocron 默认监听的 8156；
• ./config:/app/config：最关键的一个挂载——配置文件 config.yaml 与 SQLite 运行库 db.sqlite 都在 /app/config，不挂载则重启后配置与运行历史全部回到初始状态；
• ./data:/app/data：任务数据的预留挂载点。

第 2 步：启动服务：

cd /opt/gocron && docker compose up -d

实测回显：

[+] Running 3/3
 ✔ Network gocron-0.14.1-stack_default         Created
 ✔ Container gocron-0.14.1-app                 Started

第 3 步：观察启动日志，确认工具装配与服务监听：

docker logs gocron-0.14.1-app

实测回显：

time=2026-10-30T01:09:05.267Z level=INFO msg="Installing software" name=git
time=2026-10-30T01:09:10.988Z level=INFO msg=Done
time=2026-10-30T01:09:11.043Z level=INFO msg="Starting server" url=http://0.0.0.0:8156

首次启动会按配置里的 software 清单自动装配工具（默认含 git），耗时约 6 秒，随后开始监听 8156。重复重启时装配已缓存，日志直接跳到 Starting server。

第 4 步：验证服务可达与数据落盘：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8128/
ls -la /opt/gocron/config/

实测回显：

HTTP 200
-rw-r--r-- 1 root root  5230 Oct 30 09:09 config.yaml
-rw-r--r-- 1 root root 36864 Oct 30 09:09 db.sqlite

第 5 步：浏览器打开 http://<服务器IP>:8128，出现任务面板与 5 个内置示例任务即部署完成。默认未启用 OIDC 认证，UI 与 API 无需登录；生产暴露前务必按《gocron 0.14.1 配置参数详解》启用 auth.oidc 单点登录。

💡 说明：首次启动会立即生成默认 config.yaml，内含 5 个示例任务（Happy Path、Continue On Failure、Env Expansion、Timeout And Retries、Manual Long Running）。直接编辑宿主侧 /opt/gocron/config/config.yaml 保存即可生效（热重载），示例任务可以整段删除替换为自己的任务定义。

五、数据持久化说明

gocron 的全部状态集中在两个挂载目录里，备份与迁移都围绕它们：

实测验证持久化有效的方法：删除服务再重新拉起，配置与运行历史应原样保留——

docker compose down && docker compose up -d
docker logs gocron-0.14.1-app 2>&1 | tail -3

实测回显（重启后无重新生成配置的迹象，直接进入监听）：

time=2026-10-30T01:10:47.714Z level=INFO msg=Done
time=2026-10-30T01:10:47.747Z level=INFO msg="Starting server" url=http://0.0.0.0:8156

SQLite 运行库的文件头可验证其为标准 SQLite 3 格式（便于用通用工具处理）：

head -c 16 /opt/gocron/config/db.sqlite

SQLite format 3␀

六、环境变量表

gocron 的配置主体走 config.yaml 文件（逐参数见《gocron 0.14.1 配置参数详解》），分发件层面可用的环境变量以容器化场景常用的时区为主：

⚠️ 注意：不要试图用环境变量覆盖端口或认证配置——gocron 没有实现 GOCRON_* 形式的环境变量覆盖机制，全部行为配置以 config.yaml 为唯一事实源，环境变量只有 TZ 这类进程级标准变量起作用。

七、配置参数说明

部署落定后最常改的配置集中在 /opt/gocron/config/config.yaml，这里给出部署相关的最小配置块与说明（全量参数详解见《gocron 0.14.1 配置参数详解》）：

time_zone: 'Asia/Shanghai'

log_level: 'info'

delete_runs_after_days: 7

db:
  location: '.'
  name: 'db.sqlite'

software:
  - name: 'git'

server:
  address: '0.0.0.0'
  port: 8156

逐项说明：

• time_zone：全部调度计划运行的时区，修改后配置热重载即生效，是容器化部署里替代 TZ 的正确姿势；
• log_level：debug | info | warn | error 四档，热重载生效，排障时临时调到 debug 很方便；
• delete_runs_after_days：运行历史保留天数（默认 7，0 为永不清理），SQLite 文件大小的第一控制项；
• db.location：数据库目录，. 表示与 config.yaml 同目录（即挂载出来的 /opt/gocron/config），不建议改动；
• software：启动时自动装配的工具清单，备份同步场景按需加 restic、rclone、rsync、borgbackup 等；
• server.address/port：监听地址与端口，0.0.0.0 保证宿主映射可达；该段修改需重启服务（不像 jobs 段那样热重载）。

修改后验证热重载生效的实测日志：

time=2026-10-30T01:11:10.206Z level=INFO msg="Configuration reloaded" jobs=5 schedules=4 auth_enabled=false

八、配置文件挂载

两种挂载姿势的取舍：

1. 目录挂载（本文采用）：./config:/app/config。优点是首次启动自动生成的 config.yaml 直接落到宿主，db.sqlite 跟着同目录，备份就是一个 cp -a；缺点是宿主目录属主为 root（分发件以 root 运行）。
2. 单文件挂载：./config.yaml:/app/config/config.yaml 单独挂配置文件，数据库仍需另行处理。不推荐——首次启动生成默认配置的路径与单文件挂载冲突，且编辑后 inode 变化可能导致挂载失效。

验证挂载生效的最直接方法：在宿主改配置并观察服务热重载日志（见第七节回显），日志里 jobs=5 schedules=4 的计数会随你增删任务实时变化。

九、等价 docker run

不用 Compose 的单命令等价形态（参数与上面 Compose 完全一致）：

docker run -d \
  --name gocron-0.14.1-app \
  --restart unless-stopped \
  -e TZ=Asia/Shanghai \
  -p 8128:8156 \
  -v /opt/gocron/config:/app/config \
  -v /opt/gocron/data:/app/data \
  ghcr.io/flohoss/gocron:latest

实测验证与 Compose 形态行为一致：

docker logs gocron-0.14.1-app 2>&1 | tail -1

time=2026-10-30T01:10:47.747Z level=INFO msg="Starting server" url=http://0.0.0.0:8156

单机长期运行仍建议用 Compose：restart: unless-stopped、项目名隔离与 docker compose down -v 式的干净回收都是裸 docker run 不具备的。

十、常用运维命令

日常运维的高频命令速查（更多命令与 API 巡检见《gocron 0.14.1 CLI 命令与运维实操详解》）：

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart

# 查看日志（跟踪模式）
docker logs -f gocron-0.14.1-app

# 升级到新版本：拉新分发件并重建
docker compose pull && docker compose up -d

# 查看当前运行的版本
docker exec gocron-0.14.1-app /app/gocron -version

升级命令的实测回显：

time=2026-10-30T01:10:47.747Z level=INFO msg="Starting server" url=http://0.0.0.0:8156

版本查询的实测回显：

gocron v0.14.1 (built 2026-10-23T07:25:25Z, source https://github.com/flohoss/gocron)

升级前务必备份 /opt/gocron/config/（含 config.yaml 与 db.sqlite），回滚 = 把分发件 tag 改回旧版本重新 up -d。

十一、常见问题

Q1：首次启动卡在 Installing software 很久或失败？

装配工具需要访问软件源，网络受限环境会超时重试。实测环境通过 Docker 代理（HTTPS_PROXY=http://192.168.1.62:7897）约 6 秒完成 git 装配。完全离线的服务器：清空 config.yaml 的 software 清单即可跳过装配，代价是任务里不能用 git/restic 等工具（宿主已安装的命令不受影响）。

Q2：重启后配置和运行历史丢了？

/app/config 没有挂载到宿主。确认编排文件里 ./config:/app/config 存在且 /opt/gocron/config/ 下能看到 config.yaml 与 db.sqlite（验证方法见第五节）。

Q3：改了任务/时区没生效，要不要重启？

jobs、调度计划、log_level、time_zone、auth 都是热重载项，保存配置文件后看日志出现 Configuration reloaded 即生效；只有 server 段（地址、端口、CORS、限流）需要 docker compose restart。

Q4：访问面板返回 200 但想接入统一登录？

默认未启用认证（实测日志 auth_enabled=false）。在 config.yaml 的 auth.oidc 段配置 issuer/client_id/client_secret 并热重载，回调用 <对外地址>/api/auth/callback；反代场景同时配 server.app_url 与 trusted_proxies，细节见《gocron 0.14.1 配置参数详解》。

Q5：手动用 API 触发任务返回 404？

实测 POST /api/jobs/<slug>/run 返回 {"detail":"Job not found"}——该路径不是运行触发端点，触发任务请在面板上点击运行按钮。GET /api/jobs 只读巡检是实测可用的（返回任务与运行记录 JSON）。

Q6：端口 8156 能改成别的吗？

能，server.port 改掉并重启，同时把编排文件 -p 8128:8156 的右侧同步改掉。或者不动配置，只改宿主映射端口左侧（如 -p 9000:8156）——推荐后者，容器内默认值尽量少动。

十二、参考链接

• 项目仓库：https://github.com/flohoss/gocron
• 官方分发渠道：https://github.com/flohoss/gocron/pkgs/container/gocron
• 发布订阅：https://github.com/flohoss/gocron/releases.atom
• 系列文档：《gocron 0.14.1 介绍与选型指南》（版本与特性溯源）、《gocron 0.14.1 配置参数详解》（全量参数逐项解释）、《gocron 0.14.1 CLI 命令与运维实操详解》（命令与 API 运维）