dockge 日常运维手册

dockge 日常运维手册：巡检链路、栈目录与数据目录备份恢复、跨环境栈迁移、升级与回滚，以及数据库只读、引擎套接字权限、状态不同步等实测排障

dockgedockge2026/10/18

dockge 日常运维手册

目标：为已部署的 dockge 建立日常运维操作规范，覆盖日常巡检、备份与恢复、跨环境栈迁移、版本升级与回滚，以及权限类故障、状态不同步等真实排障场景。本篇所有命令与回显均已在 Ubuntu 22.04 实测通过，环境为按《dockge Docker Compose 部署指南》完成部署的 dockge 1.5.0。

一、环境信息

本篇基于以下环境开展运维实测。运维动作多数不区分版本，但涉及行为差异处（如 Console 门控）均以 1.5.0 的实际行为为准。

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • 服务引擎与编排工具：Docker Engine 29.8.1、Docker Compose v5.5.1
  • dockge 版本：1.5.0（部署方式为 Compose，部署文件位于 /opt/dockge/compose.yaml，发布物标签 louislam/dockge:1）
  • 关键路径约定（与本系列部署篇保持一致）：
    • /opt/dockge/compose.yaml——dockge 自身部署文件
    • /opt/dockge/data/——dockge 元数据目录（SQLite 数据库、JWT 密钥等）
    • /opt/stacks/——栈根目录，每个栈一个子目录
  • 演示栈：demo-stack（单服务 nginx:alpine，对外端口 8080），随部署篇创建，本篇的巡检、备份、迁移、排障均以它为例
  • 管理账号：admin（邮箱 admin@example.com）

二、日常巡检

巡检的目标是用最少的命令确认"面板活着、栈活着、数据完整"。本章四个检查点构成一条可进定时任务的巡检链路。

2.1 面板与栈服务探活

先确认面板 HTTP 服务响应正常，再抽查被管栈的业务可用性：

$ curl -s -o /dev/null -w "面板 HTTP %{http_code}\n" --max-time 5 http://127.0.0.1:5001/
面板 HTTP 200
$ curl -s -o /dev/null -w "栈服务 HTTP %{http_code}\n" --max-time 5 http://127.0.0.1:8080/
栈服务 HTTP 200

两个探活都返回 200。若面板探活异常，先看容器状态与日志（docker compose -f /opt/dockge/compose.yaml ps 与 logs）；若面板正常而栈服务异常，则在对应栈目录用命令行复核（见 2.4）。

2.2 栈目录检查

栈目录是 dockge 的"配置真身"，巡检确认目录结构与内容符合预期：

$ ls /opt/stacks/
demo-stack
$ ls -l /opt/stacks/demo-stack/
total 4
-rw-r--r-- 1 root root 98 Oct 18 09:08 compose.yaml

检查点：栈目录数量与面板列表一致；每个栈目录内 compose.yaml 存在且属主明确。若发现"面板里有、目录里没有"或相反的情况，通常是目录被手工改动，回到面板刷新即可重新对齐（面板每次列表刷新都以磁盘目录为准重新扫描）。

2.3 数据目录检查

dockge 自身的元数据（账号、JWT 密钥、设置）都在数据目录中，SQLite 数据库由主文件与 WAL 辅助文件构成：

$ du -sh /opt/dockge/data/
88K     /opt/dockge/data/
$ ls /opt/dockge/data/
db-config.json
dockge.db
dockge.db-shm
dockge.db-wal

dockge.db 是主库，-shm/-wal 是 SQLite 写前日志辅助文件（备份时应一并打包，见第三章）。目录体积长期只有几十 KB 到几 MB 量级（只存元数据，不存栈内容），若体积异常增长需检查是否有异常日志堆积。

2.4 栈状态一致性核验

dockge 面板显示的栈状态来自服务引擎的实时查询，"面板显示"与"命令行实际"天然同源。但运维中应定期核验这一一致性——尤其在有人绕过面板用命令行操作过栈的环境中。实测：先在命令行直接停止 demo-stack（不经过面板）：

$ cd /opt/stacks/demo-stack && docker compose stop
 Container demo-stack-web-1 Stopping
 Container demo-stack-web-1 Stopped
$ curl -s -o /dev/null -w "%{http_code}\n" --max-time 3 http://127.0.0.1:8080/
000

服务实例已停止（探活 000）。此时从面板视角查询该栈的状态：

$ node stack-status.mjs demo-stack
面板视角 serviceStatusList(手动停止后) => {"ok":true,"serviceStatusList":{}}
getStack => {"ok":true,"stack":{"name":"demo-stack","status":0,"tags":[],"isManagedByDockge":true,"composeFileName":"compose.yaml","endpoint":"","composeYAML":"services:\n  web:\n    image: nginx:alpine\n    restart: unless-stopped\n    ports:\n      - \"8080:80\"\n",...

面板如实地显示：服务实例列表为空、栈状态值 0（未激活）——与命令行看到的事实完全一致，没有"面板显示运行中、实际已停止"的漂移。补一次运行态核验后恢复服务：

$ cd /opt/stacks/demo-stack && docker compose start
 Container demo-stack-web-1 Starting
 Container demo-stack-web-1 Started
$ sleep 3 && curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 http://127.0.0.1:8080/
200

注意最后一条：服务实例启动后立即探活可能拿到 000（nginx 需要一两秒就绪），等待数秒重试即返回 200。巡检脚本中给业务探活留几秒重试窗口是通用好习惯。

三、备份与恢复

dockge 的备份面很窄——这正是文件式设计的红利。需要备份的只有两处：栈目录（/opt/stacks/，所有栈的 compose.yaml/.env）与数据目录（/opt/dockge/data/，账号与设置）。面板发布物本身无需备份，随时可重建。

3.1 备份范围说明

备份对象内容丢失影响恢复难度
/opt/stacks/全部栈的 compose.yaml、.env高：栈定义丢失，需重写低：拷回目录即恢复
/opt/dockge/data/dockge.db 等 SQLite 文件、JWT 密钥、db-config.json中：账号体系丢失需重新初始化低：拷回目录后重启面板
面板运行时状态无需备份—compose up -d 重建

两个目录都在文件系统上，一条 tar 命令即可全量备份。若栈内有应用数据（卷挂载的业务数据），那些属于各栈自身的备份范畴，不在 dockge 管理面内，需按各应用方案另行备份——规划备份时务必区分"栈定义"与"应用数据"。

3.2 备份实操

打包两目录到备份文件（以日期命名，便于轮转）：

$ mkdir -p /opt/backup
$ tar -czf /opt/backup/dockge-backup-$(date +%Y%m%d).tar.gz -C / opt/stacks opt/dockge/data
$ ls -lh /opt/backup/
total 4.0K
-rw-r--r-- 1 root root 1.8K Oct 18 09:10 dockge-backup-20261018.tar.gz

1.8K 的体积对应当前"单栈 + 空账号库"的规模，随栈数量增长。打包后校验归档完整性——列出内容确认两个目录都在：

$ tar -tzf /opt/backup/dockge-backup-20261018.tar.gz
opt/stacks/
opt/stacks/demo-stack/
opt/stacks/demo-stack/compose.yaml
opt/dockge/data/
opt/dockge/data/dockge.db
opt/dockge/data/dockge.db-shm
opt/dockge/data/db-config.json
opt/dockge/data/dockge.db-wal

归档内容齐全（栈目录、数据目录、SQLite 三件套与配置文件）。生产环境建议把本节命令放进 cron 每日执行，并对 /opt/backup/ 做异地同步。

3.3 恢复演练（迁移解包校验）

备份的价值在于能恢复。在同一台服务器上模拟"新环境恢复"：解包到独立目录，逐文件比对与源目录一致：

$ mkdir -p /opt/restore-test
$ tar -xzf /opt/backup/dockge-backup-20261018.tar.gz -C /opt/restore-test
$ diff -r /opt/stacks/demo-stack /opt/restore-test/opt/stacks/demo-stack
$ echo $?
0
diff 校验：一致
$ ls /opt/restore-test/opt/dockge/data/
db-config.json
dockge.db
dockge.db-shm
dockge.db-wal

diff -r 无差异输出、退出码 0，恢复内容与源完全一致。真实恢复流程即：在新服务器装好引擎与 Compose → 把归档解包到对应路径（保持 /opt/stacks、/opt/dockge 布局）→ 在 /opt/dockge 执行 docker compose up -d → 账号、栈全部原样回来（面板基于文件扫描纳管）。

四、栈迁移

栈迁移是把"一批栈"从 A 服务器搬到 B 服务器。由于栈真身就是文件，迁移的核心动作只有打包与解包两步；面板与引擎在新服务器上就位后，栈会被自动识别。

4.1 迁移要点

迁移前核对三点，避免搬过去"水土不服"：

  1. 路径一致：目标服务器的栈根目录路径必须与源一致（本例均为 /opt/stacks）。若目标用了其他路径，需要同步修改目标 dockge 的挂载与 DOCKGE_STACKS_DIR，并注意 compose.yaml 内若有相对路径引用也要检查。
  2. 端口占用：源环境各栈映射的宿主端口（如 demo-stack 的 8080）在目标环境必须空闲，冲突则迁完改端口。
  3. 镜像可达：目标环境要能拉取各栈声明的发布物（内网环境提前 docker save/load 或配好仓库凭据）。

4.2 迁移实操（打包 → 目标环境恢复 → 纳管验证）

第一步：源服务器打包栈目录（不打包运行态，只打包文件）：

$ tar -czf /tmp/stacks-migrate.tar.gz -C / opt/stacks
$ tar -tzf /tmp/stacks-migrate.tar.gz
opt/stacks/
opt/stacks/demo-stack/
opt/stacks/demo-stack/compose.yaml

第二步：传输并解包到目标服务器。演示环境在同一台服务器解包到恢复目录模拟目标环境：

$ mkdir -p /opt/restore-test
$ tar -xzf /tmp/stacks-migrate.tar.gz -C /opt/restore-test
$ diff -r /opt/stacks/demo-stack /opt/restore-test/opt/stacks/demo-stack && echo "diff 校验：一致"
diff 校验：一致

真实跨机操作时，把 /tmp/stacks-migrate.tar.gz 用 scp/rsync 传到目标服务器，解包到目标栈根目录即可。

第三步：目标环境纳管验证。目标 dockge 就位并启动后，打开面板即可在栈列表看到迁移来的 demo-stack（面板按目录扫描识别，isManagedByDockge: true），栈文件内容与源环境一致；随后在面板点 Start（或在栈目录执行 docker compose up -d）即可把栈跑起来。第三章 3.3 的解包校验就是这一步的实测记录。

迁移后建议做一次 2.4 节的状态一致性核验，确认目标环境栈状态与预期相符。

五、升级与回滚

dockge 升级很轻：拉新版发布物并重建即可，数据目录与栈目录不受影响（栈文件在宿主机、元数据经挂载保留）。

5.1 升级实操

官方 compose.yaml 使用滚动标签 louislam/dockge:1，升级 = pull + up 两步。部署文件使用 compose 简写（docker compose 的别名封装，便于在任意目录执行）：

$ cd /opt/dockge && compose pull
 Image louislam/dockge:1 Pulling
 Image louislam/dockge:1 Pulled
$ compose up -d
 Container dockge-dockge-1 Running
$ compose ps
NAME              IMAGE               COMMAND                  SERVICE   CREATED          STATUS                   PORTS
dockge-dockge-1   louislam/dockge:1   "/usr/bin/dumb-init …"   dockge    47 seconds ago   Up 47 seconds (healthy)   0.0.0.0:5001->5001/tcp, [::]:5001->5001/tcp
$ curl -s -o /dev/null -w "升级后探活: HTTP %{http_code}\n" --max-time 5 http://127.0.0.1:5001/
升级后探活: HTTP 200

实测说明：本环境发布物已是最新（1.5.0），pull 显示 "Pulled" 后 up -d 判定服务实例无需重建（Running）。当远端有新版本时，pull 会下载新层，up -d 会重建服务实例—— recreate 过程中断几秒后恢复，面板数据（账号/设置）与栈均不受影响。升级后确认两点：状态 healthy、探活 200；再按第五章 5.1 的思路留意新版本的破坏性变更（如 1.5.0 起 Console 默认禁用，见第六章 6.4）。

5.2 版本锁定与回滚

滚动标签适合追新，但生产环境更建议锁定明确版本：把部署文件中 image: louislam/dockge:1 改为具体版本（如 louislam/dockge:1.5.0），升级动作变为"改标签 → pull → up -d"，每一步版本明确可审计。

回滚即反向操作：把标签改回上一个版本号，compose up -d 重建。由于栈文件与元数据都在宿主机文件系统，发布物版本切换不影响数据；唯一需留意的是若新版本初始化过数据库结构，回滚旧版本时个别字段可能不兼容——因此升级前先做第三章的备份（两目录各几 MB，成本极低），回滚失败可整体还原。

六、常见问题与排障

本章收录实测复现过的典型故障，每例给出现象、根因与实测解决过程。排障总原则：先分清"面板进程的问题"还是"面板操作链路的问题"——前者看 docker logs dockge-dockge-1，后者看面板操作终端的实时输出（报错原文都在那里）。

6.1 数据库只读错误（SQLITE_READONLY）

现象：面板无法访问（探活 000），服务端日志反复报数据库错误。

根因：dockge 进程对数据目录没有写权限。实测触发方式——在部署文件中给服务加 user: "1000:1000" 以非特权用户运行，而数据目录属主是 root：

$ cd /opt/dockge && docker compose up -d
 Container dockge-dockge-1 Starting
 Container dockge-dockge-1 Started
$ sleep 8
$ curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 http://127.0.0.1:5001/
000
$ docker logs dockge-dockge-1 | grep -iE "error" | head -2
2026-10-18T09:11:33Z [SERVER] ERROR: Failed to prepare your database: PRAGMA journal_mode = WAL - SQLITE_READONLY: attempt to write a readonly database
2026-10-18T09:11:34Z [SERVER] ERROR: Failed to prepare your database: PRAGMA journal_mode = WAL - SQLITE_READONLY: attempt to write a readonly database

进程起来了但 SQLite 打不开写模式（PRAGMA journal_mode = WAL 需要 写权限），无限重试，面板端口无响应。

解决：把数据目录属主改为运行用户（1000:1000），重建后恢复：

$ chown -R 1000:1000 /opt/dockge/data
$ docker compose up -d
 Container dockge-dockge-1 Started
$ sleep 8 && curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 http://127.0.0.1:5001/
200

经验归纳：凡因安全加固改了运行用户（user 指令），必须同步核对所有挂载目录的属主——数据目录是必然中招的一个；栈目录若也需要面板写入（编辑/部署），属主要一并调整。官方 PUID/PGID 环境变量方案（两者必须同时设置）可让面板进程以指定属主身份运行，属同类问题的官方解法。

6.2 引擎套接字权限错误（permission denied）

现象：面板能登录、栈列表能看到，但执行停止/部署等操作失败，提示看终端输出。

根因：面板进程读不到服务引擎套接字。实测在非特权用户运行的前提下（同 6.1 的 user: "1000:1000" 场景，数据目录已修复），执行栈停止操作：

$ node stop.mjs demo-stack
stopStack(引擎套接字权限故障时) => {"ok":false,"msg":"Failed to stop, please check the terminal output for more information."}

面板操作终端里的原始错误（引擎客户端以当前用户身份连套接字被拒）：

stderr: 'permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.48/containers/json?...": dial unix /var/run/docker.sock: connect: permission denied'

解决：让面板进程获得套接字访问权。最直接的是恢复特权运行（去掉 user 指令），实测恢复后同一操作成功：

$ cd /opt/dockge && mv compose.yaml.bak compose.yaml && docker compose up -d
 Container dockge-dockge-1 Started
$ sleep 8 && curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 http://127.0.0.1:5001/
200
startStack(恢复后) => {"ok":true,"msg":"Started"}
serviceStatusList => {"ok":true,"serviceStatusList":{"web":"running"}}

若坚持非特权运行（更安全的方向），则把运行用户加入宿主机引擎套接字的属组（通常是 docker 组，groupadd/usermod -aG 处理），并在挂载时确保组 ID 匹配。要认识到该权限的分量：套接字访问权 = 主机服务引擎完全控制权，这也是官方 1.5.0 默认关闭 Console 终端的同一安全逻辑（见 6.4）。

6.3 栈状态不同步

现象：面板显示的栈状态与命令行看到的不一致（如面板"运行中"而实际已停止）。

排查：dockge 无状态缓存问题——栈状态是面板实时向引擎查询的。出现"不同步"，绝大多数是看到的是旧页面（浏览器页签停留在很久之前）或操作发生在面板之外（命令行改动后面板未刷新）。实测验证（同 2.4）：命令行停止 demo-stack 后，面板查询立即返回未激活态：

面板视角 serviceStatusList(手动停止后) => {"ok":true,"serviceStatusList":{}}
getStack => {"ok":true,"stack":{"name":"demo-stack","status":0,...}}

解决：刷新面板页面（或重新进入栈详情）即与实际一致；dockge 1.4+ 的页面在打开状态下会经 Socket.IO 推送实时更新，无需手工刷新。若刷新后仍不一致，用 docker ps -a --filter name=<栈名> 核对真实运行态，并检查是否有多套引擎环境（如面板连的引擎与命令行默认引擎不同）。

6.4 Console 终端入口消失（1.5.0 行为变化）

现象：升级到 1.5.0 或新部署后，面板左下角 Console（宿主机终端）入口不见了。

根因：这是 1.5.0 的预期行为——Release Notes 明确 Console 功能因安全原因默认禁用，需显式加环境变量 DOCKGE_ENABLE_CONSOLE=true 开启。实测关闭态调用直接被拒：

mainTerminal => {"ok":false,"msg":"Console is not enabled.","msgi18n":true}

解决：在 /opt/dockge/compose.yaml 的 environment: 段追加 DOCKGE_ENABLE_CONSOLE=true 后 docker compose up -d 重建（完整实测过程见《dockge Docker Compose 部署指南》第 7 章，开启后调用返回 {"ok":true}）。开启前请确认面板访问面受控——Console 等同于把宿主机 shell 开在网页里。

6.5 "坏栈"删不掉

现象：栈列表里有部署失败留下的栈，点删除报 "Failed to delete, please check the terminal output"。

根因：删除操作先要对栈执行 Down，栈文件本身校验不过（如端口越界）时 Down 失败，删除中断。实测案例与两种解法（修文件后再删 / 命令行处理）见《dockge Docker Compose 部署指南》第 8.3 节，此处不重复展开。

七、参考链接

  1. dockge 源码仓库与 README：https://github.com/louislam/dockge
  2. dockge 1.5.0 Release Notes（Console 默认禁用等行为变化）：https://github.com/louislam/dockge/releases/tag/1.5.0
  3. dockge 官方主页（配置生成器）：https://dockge.kuma.pet
  4. Docker Compose 官方文档（up/down/pull 命令语义）：https://docs.docker.com/compose/
  5. SQLite WAL 模式说明（理解 6.1 只读错误）：https://www.sqlite.org/wal.html
  6. 平台部署篇：《dockge Docker Compose 部署指南》（部署、初始化、首个栈与部署期排障）
  7. 平台认知篇：《dockge 1.5.0 介绍与选型指南》（架构、功能与选型对比）