v2.1.1

修正

• 关于页：删除"不提供 exec 能力"（exec 已支持，设置中开启即可）
• 关于页：功能列表补充 exec 说明
• 菜单"审计"→"操作日志"：更直观的命名，与容器日志区分

改进

• 优化了桌面版和手机端的 UI：嵌入 Noto Sans SC 中文字体（去除 Google Fonts CDN 依赖）、统一 UI 元素字号（body 14px，最小 13px）、手机端登录框居中
• 集成测试增强：test_version_consistency 新增对 base.html 和 about.html 版本号的检查，防止改版本漏改模板

---

Docker 镜像

• docker pull ghcr.io/sopyk/docker-mcpilots:v2.1.1
• docker pull sopyk/docker-mcpilots:v2.1.1

v2.1.0

新增

• Web UI 手机端适配：响应式布局纯 CSS（mobile.css），桌面版零影响
  • 汉堡菜单折叠导航
  • .table-wrap 水平滚动支持长表格
  • 容器操作切换为 <select> 下拉 + 执行按钮
  • 设置页、登录页、关于页全部适配
  • 触控友好（touch-action、min-height 按钮）
• 批量栏功能增强：容器页批量栏「全选/全部不选」独立一行 + 表格底部复制相同批量栏
• API Key 复制按钮：用户页每个 Key 输入框旁加复制按钮
• 密码持久化保护：UI 设密码后容器重启不会被 ADMIN_PASSWORD 覆盖
• 设置页说明：新增密码持久化说明及恢复默认密码操作步骤

优化

• 构建速度：新增 .dockerignore，构建上下文从 ~70MB 降至 ~1MB

修复

• Docker SDK 兼容性：修复 images.list() 不支持 limit 参数
• 移动端下拉宽度：容器操作下拉菜单 min-width: 120px
• 用户页角色下拉：手机端 min-width: 80px

v2.0.4

[v2.0.4] - 2026-07-29

新增

• UI 改进：关于页 MCP 配置代码块添加一键复制按钮，点击直接复制配置
• UI 改进：用户页名称表头添加「点击可直接编辑」提示
• list_images 新增 limit 参数：支持限制返回镜像数量

修复

• audit.sh 兼容性：修复 pip/python → pip3/python3 命令

v2.0.3

[v2.0.3] - 2026-07-25

修复

• exec_container Docker API 兼容性：去掉 demux 参数，新增 _demux_frames() 手动解码多路复用字节流，兼容 Docker API < 1.42（群晖 NAS Docker v20.x）
• list_containers Image 字段截断：无标签的镜像不再显示截断哈希 sha256:abc，改为标准的 short_id
• 模板-测试对齐：修复 test_web_routes.py 中 3 个因模板重构未同步的用例
• 版本号同步：base.html 导航栏版本标签同步至 v2.0.3

新增

• UI 测试基础设施: 引入 Playwright E2E 配置、BackstopJS 视觉对比、scripts/audit.sh 一键审计

v2.0.2

🌐 English | 简体中文

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[v2.0.2] - 2026-07-09

新增

• 自动权限迁移：首次启动时自动为三个标准角色补充缺失的权限
  • 为 admin 角色添加 network:*、volume:*
  • 为 operator/observer 角色添加 network:list、volume:list
  • 自动更新持久化的 auth.yaml 配置文件
• favicon显示：使用专用 favicon 图标，浏览器标签页显示项目 logo（使用用户提供的图片）
• 容器详情页顶部返回按钮：在页面顶部也添加返回列表按钮
• 返回按钮统一位置：容器详情页顶部和底部返回按钮均靠右对齐，保持一致
• 容器页批量操作：支持复选框选择容器，批量启动/停止/重启
  • 每行开头复选框 + 表头全选
  • 顶部批量操作栏：已选计数 + 批量启动/停止/重启 + 全选/全部不选
  • 支持二次确认
• 用户页批量删除 API Key：支持复选框选择多个 Key 批量删除
  • 每行开头复选框 + 表头全选
  • 顶部批量操作栏：已选计数 + 批量删除 + 全选/全部不选
  • 支持二次确认
• 用户页内联添加 API Key：移除独立「新增 API Key」块，改为列表底部「+ 添加 API Key」按钮，点击插入一行空白（名称/角色/Key/作用域/保存/取消）
• 多架构镜像支持：同时发布 linux/amd64 和 linux/arm64 镜像，兼容群晖 NAS（amd64）和 Mac M 系列（arm64）等设备

修复

Critical级修复

• RBAC权限完全失效：所有 MCP 工具均添加权限检查（此前仅有 exec_container 工具有权限检查！）
  • container_tools：list_containers / inspect_container / start_container / stop_container / restart_container / get_container_logs / get_container_stats / remove_container / get_container_processes / get_container_health / get_container_networks / get_container_mounts / get_container_changes
  • image_tools：list_images / inspect_image / pull_image / remove_image
  • docker_diag_tools：list_networks / list_volumes
  • diag_tools：get_system_info / get_cpu_info / get_memory_info / get_disk_info / get_network_info
• exec_container 100%崩溃：兼容 KeyConfig 被 fastmcp 序列化为 dict 的情况（修改 core/auth.py 兼容判断）
• list_volumes NoneType错误：修复 Volume 的 Options 为 None 时的访问错误（使用 (options or {}) 兜底）

Web UI 修复

• 导航栏固定问题：从 position: sticky 改成 position: fixed，完全固定在页面顶部，添加 left: 0 和 width: 100%，同时在 body 上添加 padding-top: 72px 避免内容被遮挡
• 热加载后URL参数问题：在 base.html 中添加 JS 脚本，加载完成后自动去除 ?success/error 参数，避免刷新问题
• 设置页面按钮改名：“保存设置” → “应用设置”
• 设置页面移除原始内容：不再显示 settings.yaml 原始内容
• 仪表盘卡片可点击：点击容器统计卡片跳转到容器页，点击镜像统计卡片跳转到镜像页
• favicon问题：使用独立的 favicon.jpg，不影响页面上的 logo（页面 logo 继续用 logo.jpg）
• 设置页面按钮位置正确

工具注册函数优化

• 所有 MCP 工具注册函数均添加 app_state 参数，用于权限检查
• 所有工具函数均改为 async 函数，正确使用 await ctx.get_state() 获取认证状态

[v2.0.1] - 2026-07-08

新增

• 容器执行命令：安全的 exec_container MCP 工具，支持在容器内执行命令
  • 功能开关控制（默认关闭）
  • 仅 admin 角色可用
  • 支持容器 scope 限制，建议配合专用工具容器使用
• 工具容器示例：提供 docker/docker-compose-toolbox.yml 配置，创建隔离的工具容器用于 exec 操作
• 镜像管理页面：Web UI 新增镜像列表页（/ui/images），查看镜像仓库、标签、大小、创建时间
• 容器状态颜色：Web UI 容器列表状态徽章颜色区分（Running 绿色、Restarting/dead 红色、Exited/Created 灰色）

改进

• Host 头保护移除：移除 host_origin_protection 和 allowed_hosts 配置项，避免误操作导致反代访问被阻断
• 关于页修复：修复导航栏和 500 错误问题
• 登录页优化：添加 logo 和标语"给 Agent 一双管理 Docker 的手"
• 设置页面优化：添加功能开关配置、密码修改功能

[v2.0.0] - 2026-07-07

新增

• Web UI 界面：完整的图形化管理界面（/ui/）
  • 仪表盘：CPU 内存使用率环形图、容器/镜像计数、最近审计日志
  • 容器列表：查看所有容器、启停/删除/查看详情
  • 用户管理：创建/编辑/删除 API Key，支持修改 Key 名称、角色、权限和范围
  • 审计日志：查看所有操作记录（筛选功能）
  • 系统设置：编辑系统设置（端口、时区、功能开关）、修改管理员密码
  • 关于页：项目介绍、Agent 配置示例、版本信息
• Admin 认证系统：Web UI 用户名密码登录（bcrypt 加密存储）
• CSRF 防护：所有 POST 请求需要 CSRF Token
• 审计日志：记录所有 MCP 和 Web UI 操作
• 时区支持：配置时区选项，显示本地化时间
• 静态资源：支持子目录（/static/assets），正确识别图片 mime 类型

改进

• 模板安全优化：使用条件块代替未加引号的 Jinja2 表达式
• 完整的单元/集成/端到端测试（130+ 个用例，100% 覆盖核心模块）

修复

• 修复静态文件路由不支持子目录问题
• 修复 semgrep 发现的安全隐患（subprocess shell 仅用于测试、模板安全加固）

[1.0.0] - 2026-07-04

首次正式发布。

---

v1.0.0 首次正式发布

新增

• MCP Server 核心功能：基于 FastMCP 3.x 的 Docker 管理服务

  • 容器管理：list_containers / inspect_container / start_container / stop_container / restart_container / remove_container
  • 容器日志：get_container_logs（支持 tail / since / until / timestamps 时间段排查）
  • 容器资源：get_container_stats（CPU / 内存 / 网络实时占用）
  • 容器诊断（新增 8 个工具）：
    • get_container_processes：容器内进程列表（排查"卡死"）
    • get_container_health：健康检查状态 + 失败日志（排查"不健康"）
    • get_container_networks：IP / 网关 / DNS / 端口映射（排查"连不上网"）
    • get_container_mounts：挂载卷 / 绑定路径 / 读写权限（排查"数据丢失/权限不对"）
    • get_container_changes：文件系统增删改（排查"容器里改了什么"）
  • 镜像管理：list_images / pull_image / remove_image / inspect_image
  • 网络拓扑：list_networks（所有 Docker 网络及连接的容器）
  • 卷清单：list_volumes（所有卷及挂载点）
  • 系统诊断：get_system_info / get_cpu_info / get_memory_info / get_disk_info / get_network_info

• 权限模型：RBAC 三角色（admin / operator / observer），支持容器级 scope（include/exclude 通配符）

• 认证系统：API Key 认证，支持 YAML 配置或环境变量，认证状态跨请求持久化

• 群晖 NAS 适配：

  • PUID/PGID 环境变量自动调整运行用户权限
  • gosu 降权安全运行
  • 提供两种部署 compose（预构建镜像版 / 源码构建版），适用于群晖等 NAS 及通用 Linux
  • Docker socket 权限问题根因修复

• VPS 宿主机直装支持：无需 Docker 嵌套，资源占用最低，支持 systemd / nginx 反代 / TLS

改进

• Docker 相关文件统一隔离到 docker/ 子目录
• 镜像体积优化（.dockerignore 排除干扰，75MB vs 原 1.2GB）
• VPS 部署文档（含 systemd / nginx 反代 / TLS / 防火墙）
• 日志功能增强：RFC3339 时间格式 + 相对时间（"1h"/"30m"/"2d"）
• FastMCP 3.4.2 API 兼容性修复

修复

• Docker socket 权限问题（gosu 降权清除补充组）
• Docker SDK 连接不稳定（显式指定 unix socket 路径）
• get_container_changes 使用正确的 SDK 方法 diff()
• Auth 中间件请求头过滤（authorization 头需显式保留）
• Auth 状态跨请求持久化（serializable=True）

---

[0.1.4] - 2026-07-04

Added

• Enhanced container diagnostics (8 new tools around core "troubleshooting" goal)
  • get_container_processes: container process list (debugging "stuck" containers)
  • get_container_health: health check status + failure logs (debugging "unhealthy" containers)
  • get_container_networks: IP / gateway / DNS / port mappings (debugging "network issues")
  • get_container_mounts: volumes / bind mounts / rw permissions (debugging "data loss/permissions")
  • get_container_changes: filesystem diff (debugging "what changed in container")
  • inspect_image: entrypoint / env vars / build layers (debugging "image issues")
  • list_networks: all Docker networks and connected containers
  • list_volumes: all volumes and mount points
• Enhanced logs: since/until/timestamps params with RFC3339 and relative time support
• inspect_container returns complete diagnostic info (state / health / config / network / mounts)
• VPS host deployment guide (systemd / nginx reverse proxy / TLS / firewall)

Changed

• Docker files isolated to docker/ subdirectory
• docs/superpowers/ renamed to docs/specs/ and docs/plans/
• README fully updated (features, deployment, file structure)

Fixed

• get_container_changes using correct SDK method diff()
• diff() returns None on some Docker platforms (now defaults to empty list)
• since/until relative time parsing to datetime before传给 Docker SDK
• Unit test mocks aligned with new timestamps param

[0.1.3] - 2026-07-04

Fixed

• Docker socket permission issue: gosu drops supplementary groups, making group_add in compose ineffective. Root identity now changes docker.sock group to mcpuser's primary group (PGID) in entrypoint.sh.
• Docker SDK connection instability: docker.from_env() may fail to recognize socket path. Changed to explicit unix:///var/run/docker.sock.

[0.1.2] - 2026-07-03

Fixed

• FastMCP 3.4.2 API compatibility: get_state() doesn't accept default=None param.
• Auth middleware header filtering: get_http_headers() filters authorization by default; must explicitly use include={"authorization"}.
• Auth state persistence across requests: set_state() requires serializable=True.

Changed

• .dockerignore reduced image size from 1.2GB to 75MB.
• Unified image tag and internal version number.

[0.1.1] - 2026-07-03

Added

• PUID/PGID support: entrypoint.sh auto-adjusts UID/GID for NAS mount permissions.
• gosu privilege drop: container runs as root for permission fix, then drops to normal user.
• Synology NAS compose file: separate file without build step, uses pre-loaded images.

[0.1.0] - 2026-07-03

Added

• FastMCP-based MCP Server running in Docker container
• Container management MCP Tools (list/inspect/start/stop/restart/logs/stats/remove)
• Image management MCP Tools (list/pull/remove)
• System diagnostics MCP Tools (CPU/memory/disk/network/system info)
• RBAC permission system with admin/operator/observer roles
• Container-level scope access control (include/exclude wildcard patterns)
• API Key authentication via YAML config or environment variables
• Config and Secrets separation with persistent volume mounts
• Auto-generation of default config templates on first startup
• Health check endpoint (/health)
• Dockerfile and docker-compose.yml for Synology NAS deployment

v2.0.1

v2.0.1

新增

• 容器执行命令：安全的 exec_container MCP 工具，支持在容器内执行命令
  • 功能开关控制（默认关闭）
  • 仅 admin 角色可用
  • 支持容器 scope 限制，建议配合专用工具容器使用
• 工具容器示例：提供 docker/docker-compose-toolbox.yml 配置，创建隔离的工具容器用于 exec 操作
• 镜像管理页面：Web UI 新增镜像列表页（/ui/images），查看镜像仓库、标签、大小、创建时间
• 容器状态颜色：Web UI 容器列表状态徽章颜色区分（Running 绿色、Restarting/dead 红色、Exited/Created 灰色）

改进

• Host 头保护移除：移除 host_origin_protection 和 allowed_hosts 配置项，避免误操作导致反代访问被阻断
• 关于页修复：修复导航栏和 500 错误问题
• 登录页优化：添加 logo 和标语"给 Agent 一双管理 Docker 的手"
• 设置页面优化：添加功能开关配置、密码修改功能
• 导航栏版本号：显示当前版本号

Docker 镜像

• Docker Hub: sopyk/docker-mcpilots:v2.0.1
• GHCR: ghcr.io/sopyk/docker-mcpilots:v2.0.1

v2.0.0 - Web UI 发布

🎉 Docker-MCPilotS v2.0.0

给 Agent 一双管理 Docker 的手

✨ 新增

• Web UI 界面：完整的图形化管理界面（/ui/）
  • 仪表盘：CPU 内存使用率环形图、容器/镜像计数、最近审计日志
  • 容器列表：查看所有容器、启停/删除/查看详情
  • 用户管理：创建/编辑/删除 API Key，支持修改 Key 名称、角色、权限和范围
  • 审计日志：查看所有操作记录（筛选功能）
  • 系统设置：编辑系统设置（端口、时区、功能开关）、修改管理员密码
  • 关于页：项目介绍、Agent 配置示例、版本信息
• Admin 认证系统：Web UI 用户名密码登录（bcrypt 加密存储）
• CSRF 防护：所有 POST 请求需要 CSRF Token
• 审计日志：记录所有 MCP 和 Web UI 操作
• 时区支持：配置时区选项，显示本地化时间
• 静态资源：支持子目录（/static/assets），正确识别图片 mime 类型
• 环境变量支持：ADMIN_USERNAME / ADMIN_PASSWORD / INITIAL_API_KEYS 环境变量初始化管理员账号和 API Key

🚀 部署

• Docker Hub: sopyk/docker-mcpilots:v2.0.0
• GHCR: ghcr.io/sopyk/docker-mcpilots:v2.0.0

📝 完整变更日志

详见 CHANGELOG.md

v1.0.0

v1.0.0 首次正式发布

新增

• MCP Server 核心功能：基于 FastMCP 3.x 的 Docker 管理服务

  • 容器管理：list_containers / inspect_container / start_container / stop_container / restart_container / remove_container
  • 容器日志：get_container_logs（支持 tail / since / until / timestamps 时间段排查）
  • 容器资源：get_container_stats（CPU / 内存 / 网络实时占用）
  • 容器诊断（新增 8 个工具）：
    • get_container_processes：容器内进程列表（排查"卡死"）
    • get_container_health：健康检查状态 + 失败日志（排查"不健康"）
    • get_container_networks：IP / 网关 / DNS / 端口映射（排查"连不上网"）
    • get_container_mounts：挂载卷 / 绑定路径 / 读写权限（排查"数据丢失/权限不对"）
    • get_container_changes：文件系统增删改（排查"容器里改了什么"）
  • 镜像管理：list_images / pull_image / remove_image / inspect_image
  • 网络拓扑：list_networks（所有 Docker 网络及连接的容器）
  • 卷清单：list_volumes（所有卷及挂载点）
  • 系统诊断：get_system_info / get_cpu_info / get_memory_info / get_disk_info / get_network_info

• 权限模型：RBAC 三角色（admin / operator / observer），支持容器级 scope（include/exclude 通配符）

• 认证系统：API Key 认证，支持 YAML 配置或环境变量，认证状态跨请求持久化

• 群晖 NAS 适配：

  • PUID/PGID 环境变量自动调整运行用户权限
  • gosu 降权安全运行
  • 提供两种部署 compose（预构建镜像版 / 源码构建版），适用于群晖等 NAS 及通用 Linux
  • Docker socket 权限问题根因修复

• VPS 宿主机直装支持：无需 Docker 嵌套，资源占用最低，支持 systemd / nginx 反代 / TLS

改进

• Docker 相关文件统一隔离到 docker/ 子目录
• 镜像体积优化（.dockerignore 排除干扰，75MB vs 原 1.2GB）
• VPS 部署文档（含 systemd / nginx 反代 / TLS / 防火墙）
• 日志功能增强：RFC3339 时间格式 + 相对时间（"1h"/"30m"/"2d"）
• FastMCP 3.4.2 API 兼容性修复

修复

• Docker socket 权限问题（gosu 降权清除补充组）
• Docker SDK 连接不稳定（显式指定 unix socket 路径）
• get_container_changes 使用正确的 SDK 方法 diff()
• Auth 中间件请求头过滤（authorization 头需显式保留）
• Auth 状态跨请求持久化（serializable=True）

---

v1.0.0 First Official Release

Added

• MCP Server Core Features: Docker management service based on FastMCP 3.x

  • Container management: list_containers / inspect_container / start_container / stop_container / restart_container / remove_container
  • Container logs: get_container_logs (supports tail / since / until / timestamps for time-range troubleshooting)
  • Container resources: get_container_stats (real-time CPU / memory / network usage)
  • Container diagnostics (8 new tools):
    • get_container_processes: process list inside container (troubleshooting "stuck" state)
    • get_container_health: health check status + failure logs (troubleshooting "unhealthy" state)
    • get_container_networks: IP / gateway / DNS / port mappings (troubleshooting "no network access")
    • get_container_mounts: mounted volumes / bind paths / read-write permissions (troubleshooting "data loss/permission issues")
    • get_container_changes: filesystem additions, deletions and modifications (troubleshooting "what changed in container")
  • Image management: list_images / pull_image / remove_image / inspect_image
  • Network topology: list_networks (all Docker networks and connected containers)
  • Volume inventory: list_volumes (all volumes and mount points)
  • System diagnostics: get_system_info / get_cpu_info / get_memory_info / get_disk_info / get_network_info

• Permission Model: RBAC three roles (admin / operator / observer), supports container-level scope (include/exclude wildcards)

• Authentication System: API Key authentication, supports YAML config or environment variables, auth state persisted across requests

• Synology NAS Adaptation:

  • PUID/PGID environment variables auto-adjust runtime user permissions
  • gosu privilege drop for secure execution
  • Provides two deployment compose files (pre-built image version / source build version), suitable for Synology NAS and general Linux
  • Root cause fix for Docker socket permission issue

• VPS Host Direct Installation Support: No nested Docker required, minimal resource footprint, supports systemd / nginx reverse proxy / TLS

Changed

• Docker-related files uniformly isolated to docker/ subdirectory
• Image size optimization (.dockerignore excludes interference, 75MB vs original 1.2GB)
• VPS deployment docs (including systemd / nginx reverse proxy / TLS / firewall)
• Logging enhancement: RFC3339 time format + relative time ("1h"/"30m"/"2d")
• FastMCP 3.4.2 API compatibility fix

Fixed

• Docker socket permission issue (gosu privilege drop clears supplementary groups)
• Docker SDK connection instability (explicitly specify unix socket path)
• get_container_changes uses correct SDK method diff()
• Auth middleware header filtering (authorization header must be explicitly preserved)
• Auth state persistence across requests (serializable=True)