星战科技xingzhan.cloud
返回市场
Docker文本用户界面

Docker文本用户界面

作者：eviltik0 星标更新：2025-11-23
安装使用来源：spider==github.com

项目介绍

Docker TUI

一个现代且快速的终端用户界面（TUI），用于管理Docker容器，使用Go和Bubbletea构建。

Docker TUI Go 版本 MCP 服务器 许可证

功能

  • 🐳 容器管理（启动/停止/重启/暂停/移除）
  • 📋 实时日志流，支持正则表达式过滤
  • 📊 每个容器的CPU监控
  • 🖱️ 支持鼠标和键盘
  • 🤖 与Claude Desktop集成的MCP服务器
  • 💾 单一可执行文件，无依赖项

演示

安装

使用 go install

go install github.com/eviltik/docker-tui@latest

从 GitHub 发布页面下载

从发布页面下载预编译的二进制文件：

# Linux (amd64)
curl -L https://github.com/eviltik/docker-tui/releases/latest/download/docker-tui-linux-amd64.tar.gz | tar xz
sudo mv docker-tui /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/eviltik/docker-tui/releases/latest/download/docker-tui-darwin-arm64.tar.gz | tar xz
sudo mv docker-tui /usr/local/bin/

从源码安装

# 克隆仓库
git clone https://github.com/eviltik/docker-tui.git
cd docker-tui

# 构建二进制文件
make build

# 系统范围安装（可选）
sudo make install

使用方法

简单运行二进制文件：

./docker-tui

或者如果已系统范围安装：

docker-tui

命令行选项

docker-tui [OPTIONS]

选项：

  • --demo - 隐藏容器名称前缀（删除到第一个下划线之前的文本）- 适用于演示
  • --debug-monitor - 显示调试指标（协程数、文件描述符、内存、活跃流）
  • --logs-buffer-length SIZE - 日志缓冲区的最大行数（默认：10000，最小：100）
  • --mcp-server - 启用MCP HTTP服务器（默认端口：9876）
  • --mcp-port PORT - 设置MCP服务器端口（默认：9876）
  • --help, -h - 显示带有所有选项和快捷键的帮助信息

示例：

docker-tui                                    # 正常模式运行
docker-tui --demo                             # 演示模式运行（干净的容器名称）
docker-tui --debug-monitor                    # 显示调试指标
docker-tui --logs-buffer-length 50000         # 使用5万行的日志缓冲区
docker-tui --mcp-server                       # 在9876端口上启用MCP服务器
docker-tui --mcp-server --mcp-port 9000       # 在自定义端口上启用MCP服务器
docker-tui --help                             # 显示帮助

键盘快捷键

容器列表视图

键动作
↑/↓上下导航
PgUp/PgDown跳转10项
Home/End跳转到第一/最后一项
SPACE切换选择
Shift+↑/↓范围选择
A选择所有容器
Ctrl+A选择所有正在运行的容器
X清除选择
I反转选择
ENTER 或 L显示所选容器的日志
S启动所选容器
K杀死（停止）所选容器
R重启所选容器
P暂停/取消暂停所选容器
D移除所选容器
/过滤容器（支持正则表达式）
M显示MCP服务器日志（当启用--mcp-server时）
Q/ESC退出（带确认）或清除过滤
Ctrl+C立即退出

日志视图

键动作
↑/↓按行滚动日志
PgUp/PgDown分页上下滚动
Home/End跳转到顶部/底部
ENTER插入时间戳标记
C切换彩色背景的开关
/过滤日志（子字符串搜索）
Q/ESC返回容器列表或清除过滤

确认对话框

键动作
Y确认操作
N 或 Q/ESC取消

鼠标支持

动作效果
左键点击移动光标并切换选择
双击显示所点击容器的日志
鼠标滚轮上下滚动容器列表

功能详解

多容器选择

  • 使用 SPACE 切换单个容器
  • 使用 Shift+↑/↓ 进行范围选择
  • 使用鼠标点击选择容器
  • 已选中的容器会标记黄色 ✓
  • 执行的操作会应用到所有选中的容器

鼠标交互

  • 单击：移动光标到容器并切换选择
  • 双击：立即显示所点击容器的日志
  • 鼠标滚轮：上下滚动容器列表
  • 无缝配合键盘快捷键

日志流

  • 同时查看多个容器的日志
  • 每行日志显示容器名称，并带有彩色背景以便识别
  • 使用 C 键切换彩色背景的开关（便于复制日志）
  • 容器名称对齐以提高可读性
  • 如果在底部，日志会自动滚动
  • 按 ENTER 插入时间戳标记
  • 容器重启后自动重新连接
  • 实时过滤，支持子字符串搜索（/ 键）

过滤

容器列表过滤：

  • 按 / 进入过滤模式
  • 支持正则表达式模式（不区分大小写）
  • 无效的正则表达式模式会高亮显示为红色
  • 按 ENTER 应用过滤或按 ESC 取消
  • 过滤条件显示在标题栏中，带有 🔍 图标
  • 隐藏的容器数量显示在统计信息中

日志过滤：

  • 按 / 进入过滤模式
  • 使用不区分大小写的子字符串搜索
  • 实时过滤，随着输入实时更新
  • 过滤应用于日志内容（去除ANSI代码以确保准确匹配）
  • 按 Q 或 ESC 清除过滤

容器操作

所有操作都支持单个和多个容器：

  • 启动：启动已停止的容器
  • 停止：优雅地停止正在运行的容器（10秒超时）
  • 重启：重启容器（10秒超时）
  • 暂停/取消暂停：智能切换——暂停正在运行的容器，取消暂停已暂停的容器
  • 移除：强制移除容器（带确认）

多容器操作（>1个选中）会显示一个确认对话框，列出受影响的容器。

异常日志

所有崩溃都会自动捕获并记录到 /tmp/docker-tui-crash.log 中，包括：

  • 导致崩溃的协程及其所有其他协程的完整堆栈跟踪
  • 系统指标（协程数、文件描述符、内存、GC统计）
  • 协程名称标识，便于调试
  • 时间戳和错误详情

如果Docker TUI崩溃，请检查崩溃日志以获取详细的诊断信息：

cat /tmp/docker-tui-crash.log

可配置的日志缓冲区

使用 --logs-buffer-length 自定义日志缓冲区大小：

docker-tui --logs-buffer-length 50000  # 5万行缓冲区
docker-tui --logs-buffer-length 1000   # 1千行缓冲区（低内存）

默认：10,000 行。最小：100 行。

更大的缓冲区允许查看更多的历史日志，但会消耗更多内存。根据需要和可用资源进行调整。

MCP 服务器（模型上下文协议）

Docker TUI 包含一个内置的 MCP HTTP 服务器，它暴露了 Docker 容器管理能力给像 Claude Code 这样的AI助手。该服务器与 TUI 并行运行（或仅在 HTTP 模式下运行而无需 TTY），并提供了对容器操作和日志的程序化访问。

功能

  • HTTP 传输：支持 JSON-RPC 2.0 和 Server-Sent Events (SSE)
  • 无状态模式：每个请求都是独立的，不需要会话管理
  • 6 个强大工具：完整的容器生命周期管理
  • 实时日志流：共享 LogBroker 架构，高效访问日志
  • 自动刷新：容器列表每5秒更新一次
  • CORS 启用：与基于Web的AI助手兼容
  • 高性能：缓存 CPU 统计数据，即时响应（约6毫秒响应 list_containers）

可用工具

  1. list_containers - 列出所有 Docker 容器的状态和资源使用情况

    • 按状态过滤（运行/停止/全部）
    • 按名称过滤（不区分大小写的子字符串）
    • 返回：容器ID、名称、状态、状态、CPU%、日志速率、端口

  2. get_logs - 搜索和获取容器日志，具有高级过滤功能

    • 全局搜索：留空 'containers' 以跨所有容器搜索
    • 支持正则表达式或子字符串过滤（关键词如 "error", "warn"）
    • 可配置的行限制（默认：100，最大：10000）
    • 自动去除 ANSI 代码以确保准确过滤
    • 返回：格式化的日志，带有容器名称前缀

  3. get_stats - 获取详细的资源统计信息

    • 实时 CPU 使用率百分比
    • 可选的10值CPU历史
    • 日志速率（行/秒）
    • 当前状态和端口

  4. start_container - 启动已停止的容器

    • 支持部分名称匹配
    • 支持批量操作多个容器
    • 返回：每个容器的成功/失败状态

  5. stop_container - 停止正在运行的容器

    • 10秒优雅超时
    • 支持批量操作
    • 返回：每个容器的成功/失败状态

  6. restart_container - 重启容器

    • 10秒超时
    • 适用于任何容器状态
    • 返回：每个容器的成功/失败状态

与 Claude Code 集成

方法1：命令行（推荐）

# 启动 MCP 服务器
docker-tui --mcp-server --mcp-port 9876 &

# 添加到 Claude Code
claude mcp add-json docker-tui '{
  "type": "http",
  "url": "http://localhost:9876/mcp"
}'

方法2：配置文件

添加到你的 ~/.claude.json：

{
  "mcpServers": {
    "docker-tui": {
      "type": "http",
      "url": "http://localhost:9876/mcp"
    }
  }
}

然后启动服务器：

docker-tui --mcp-server --mcp-port 9876

方法3：项目级配置

创建 .mcp.json 在你的项目中：

{
  "mcpServers": {
    "docker-tui": {
      "type": "http",
      "url": "http://localhost:9876/mcp"
    }
  }
}

测试 MCP 服务器

安装完成后，你可以使用 Claude Code 测试每个工具。这里有一些示例提示：

1. 列出容器

展示我所有的正在运行的 Docker 容器

列出所有容器，包括已停止的

查找名称中含有 "nginx" 的容器

2. 获取日志

展示我的 nginx 容器最后50行日志

获取 redis 容器的日志并过滤错误

展示所有名称匹配 "api" 的容器的日志，其中包含 "WARNING"

获取 mongodb 容器最后10行日志，使用正则表达式过滤 "connection.*failed"

3. 获取统计信息

我的运行容器的 CPU 使用率是多少？

展示 postgres 容器的详细统计信息，包括 CPU 历史

获取所有名称匹配 "web" 的容器的资源使用情况

4. 启动容器

启动 nginx 容器

启动名称中含有 "test" 的所有容器

5. 停止容器

优雅地停止 redis 容器

停止名称匹配 "dev" 的所有容器

6. 重启容器

重启 mongodb 容器

重启所有 api 容器

高级多工具工作流程

列出所有正在运行的容器，然后显示使用最多 CPU 的容器的日志

查找名称中含有 "staging" 的容器，获取它们的统计信息，并重启任何 CPU 使用率超过80%的容器

展示所有已停止的容器，然后启动名称中含有 "service" 的容器

HTTP-Only 模式

在没有TTY的环境中（如 Docker 或 systemd），服务器会自动进入 HTTP-Only 模式：

# 在 Docker 容器或后台服务中
docker-tui --mcp-server --mcp-port 9876
# 输出：正在以 HTTP-Only 模式运行（未检测到 TTY）

架构

  • 传输：来自 go-mcp 的 StreamableHTTPServerTransport
  • 协议：支持 SSE 的 JSON-RPC 2.0
  • 日志流：与 TUI 共享的 LogBroker 实例
  • CPU 统计缓存：每5秒更新一次的共享缓存，用于即时的 MCP 响应
  • 自动发现：容器列表每5秒刷新一次
  • 优雅关闭：接收到 SIGINT/SIGTERM 信号时进行适当的清理

开发

前提条件

  • Go 1.24 或更高版本
  • 安装并运行 Docker
  • 访问 Docker 套接字（/var/run/docker.sock）

构建

# 为当前平台构建
make build

# 不构建直接运行
make run

# 为所有平台构建
make dist-all

# 清理构建产物
make clean

# 运行测试
make test

# 格式化代码
make fmt

故障排除

权限被拒绝

如果你在访问 Docker 套接字时遇到“权限被拒绝”：

# 将你的用户添加到 docker 组
sudo usermod -aG docker $USER

# 或者使用 sudo 运行（不推荐）
sudo ./docker-tui

Docker 未运行

确保 Docker 守护进程正在运行：

# 检查 Docker 状态
systemctl status docker

# 启动 Docker
sudo systemctl start docker

贡献

欢迎贡献！请随时提交 Pull Request 或通过打开问题来提出改进建议。

许可证

MIT 许可证 - 详情见 LICENSE 文件

作者

eviltik

致谢