飞牛 Docker 容器管理增强版（docker-center）开发文档

这个项目是什么

docker-center 是一个面向多应用用户的 Docker 管理与监控面板。它的核心不是「列出一堆容器」，而是把容器按应用（Compose 项目 / 单容器）聚合：打开面板就能看到哪个应用坏了、占了多少资源、磁盘还能清理什么，异常的应用永远排在最前面。

与 Portainer、Netdata 这类方案相比，它多了三件事：按应用聚合管理、异常优先排序、优化建议一键清理。面板本身很轻——单容器常驻约 40MB，无 agent、无 Prometheus、无数据库，数据以小时账本存本地 JSON，不依赖任何云服务。

安全前提：面板挂载 /var/run/docker.sock（等同宿主 root），不要直接暴露公网，应放在内网或带鉴权的反代后面。

技术栈与架构

后端：Node.js + Express 4 + dockerode 4。server/index.js 是主服务（含全部 API、采样、排序与优化建议逻辑），server/cloud.js 负责与授权中心（公告 / 版本 / 安装统计）交互。
前端：原生 HTML/CSS/JS（public/index.html、public/app.js、public/style.css），无框架、无构建步骤，改动后随容器重建直接生效。
存储：无数据库。设置写 data/settings.json；流量 / CPU / 内存历史按小时账本落本地 JSON；趋势曲线与 24 小时可用率保存在内存中，服务重启后重新累积。
部署：Docker 单容器，默认端口 7030，mem_limit: 384m，restart: always。

仓库结构

路径	作用
`server/index.js`	主服务：容器/应用/镜像/网络/备份/告警 API、3 秒采样循环
`server/cloud.js`	授权中心客户端：版本检查、公告、安装登记与心跳
`public/`	前端单页（`index.html` + `app.js` + `style.css`）
`docker-compose.yml`	默认编排（挂 docker.sock、`/:host:ro`、`./data:/data`）
`Dockerfile`	运行镜像构建
`install.sh`	一键安装脚本：查环境 → 探测 docker 目录 → 拉源码 → 写 `.env` → 起容器 → 等健康检查
`scripts/push-image.sh`	镜像发布脚本（aliyun / tencent / dockerhub / gitea-lan）
`docs/publish-image.md`	各 registry 发布流程、踩坑记录与实测数据
`screenshots/`	README 用的真实界面截图（已在 `.dockerignore` 中排除）
`CHANGELOG.md`	更新日志（按功能点逐条记录）

本地开发环境

git clone http://127.0.0.1:3200/jinghui/docker-center.git
cd docker-center
npm install
npm start          # 即 node server/index.js（package.json 版本号 1.0.4）

依赖只有 express 与 dockerode 两个。开发进程需要能读到 Docker：把 /var/run/docker.sock 暴露给进程，或者直接在容器里开发（docker compose up -d --build）。前端改完无需编译，重建容器即可看到效果。

配置项说明

服务端环境变量（docker-compose.yml 中已设置的默认值）：

配置键	默认值	含义
`PORT`	`7030`	面板监听端口
`SAMPLE_MS`	`3000`	资源采样间隔（毫秒）
`INSPECT_MS`	`15000`	inspect 刷新间隔（重启次数、健康状态）
`DISK_PATH`	`/host/vol1`	磁盘可用率统计路径
`SETTINGS_PATH`	`/data/settings.json`	设置文件路径
`COMPOSE_ROOT`	`/vol1/1000/HD1/docker`	扫描 Compose 文件、判断「未启动应用」的根目录
`TZ`	`Asia/Shanghai`	时区
`HUB_URL` / `HUB_API_KEY` / `HUB_PROJECT_ID`	未设置	指向自建授权中心时的三个地址/凭据
`HUB_DISABLED`	未设置	设为 `1` 关闭上报（也可在 `data/settings.json` 里把 `telemetry` 设为 `false`）

install.sh 可覆盖的变量：

变量	默认值	说明
`PORT`	`7030`	面板访问端口
`COMPOSE_ROOT`	自动探测（飞牛 `/vol1/1000/HD1/docker`，其次 `~/docker`）	扫描 compose 文件的根目录
`INSTALL_DIR`	`/vol1/1000/HD1/docker/docker-center`	源码与数据目录
`CONTAINER_NAME`	`docker-center`	容器名
`REPO_URL`	`https://gitee.com/jinghui111/docker-center`	换源用，内网可指向自建 Gitea

构建与发布

docker compose up -d --build     # 代码改动后重建
docker compose logs -f           # 看日志
docker compose restart           # 重启

镜像发布（细节见 docs/publish-image.md）：

docker login <registry> -u <用户名>
NAMESPACE=<命名空间> ./scripts/push-image.sh aliyun 1.0.0    # 或 tencent / dockerhub / gitea-lan

当前对外镜像有两个，内容完全一致：jpccr.ccs.tencentyun.com/jinghui/docker-center:1.0.1（腾讯云 TCR 东京节点，主地址）与 gitea.88531.cn/jinghui/docker-center:1.0.1（自建 Gitea，国内备用），均支持匿名拉取。

部署方式

一条命令安装（新机器）：

curl -fsSL https://gitee.com/jinghui111/docker-center/raw/main/install.sh | bash

脚本会依次：检查环境 → 自动探测 docker 目录 → 拉源码 → 写 .env → docker compose up -d --build → 等健康检查通过 → 打印访问地址。升级再跑一次同一条命令即可（已有仓库会 fetch + reset --hard 后重建）。

不想编译源码就直接用预构建镜像的 compose：

services:
  docker-center:
    image: jpccr.ccs.tencentyun.com/jinghui/docker-center:1.0.1
    container_name: docker-center
    ports: ["7030:7030"]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /:/host:ro
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
    restart: always

二次开发要点

采样：每 3 秒并行拉一次所有运行中容器的 stats；CPU% 用 cpu_stats / precpu_stats 差值乘核数；内存扣掉 inactive_file；网络与磁盘速率靠相邻采样差分。
inspect（重启次数、健康状态）每 15 秒才刷一遍——每 3 秒 inspect 六十多个容器太重。
Docker 日志是 8 字节头的多路复用流，用 demuxLogs 手动解帧；modem.demuxStream 在 follow=false 时会挂住请求。
排序比较器统一按「降序」实现，order=asc 时取反，否则会出现 desc 变升序的 bug。
应用详情是独立视图状态（app-detail），轮询刷新时必须保住它，否则每 4 秒会被看板覆盖。
自动刷新是「无感」的：输入框聚焦、抽屉打开、处于设置/备份页、或 5 秒内有键鼠操作时跳过重绘，静默刷新保留滚动位置——改动这段逻辑时别破坏这个约定。
优化建议每次刷新（3 秒）重新计算，但 Docker 磁盘统计缓存 60 秒，避免频繁扫描镜像层；同类问题会合并成一条。
应用归属依赖 com.docker.compose.project 标签；手工 docker run 的容器各自算一个「单容器应用」。
已知限制：曲线与可用率在内存里，重启服务后重新累积；不提供在线改容器配置，改配置走 Compose 或重建容器。

授权中心与遥测

面板右上角常驻版本号，有新版本时高亮为 v当前 → v最新，公告走同一个铃铛入口。上报内容只有三项：随机生成的机器码、当前版本号、运行平台，不含容器名、镜像名、日志或业务数据；设置 HUB_DISABLED=1 即可关闭。授权中心挂掉时面板功能完全不受影响（失败开放）——二次开发时不要把任何核心功能绑在这条链路上。