docker-ops

通过 docker-socket-proxy 管理 Docker 容器：状态报告、日志分析和重启操作。

前置条件

• docker CLI 已在 PATH 中可用
• jq 已在 PATH 中可用
• DOCKER_HOST 环境变量已预先配置（不要手动覆盖）
• 代理工作区根目录下存在 whitelist.yml 文件

白名单检查

在执行任何 Docker 命令前，必须检查 SYSCTL_WHITELIST_PATH 环境变量。

**如果 SYSCTL_WHITELIST_PATH 未设置或为空：**

• 不得执行任何 Docker 命令
• 回复内容为："⚠️ SYSCTL_WHITELIST_PATH 未配置。请在容器中设置该环境变量，指向白名单 YAML 文件路径。"
• 此规则适用于所有请求，无例外

如果已设置： 从该路径读取白名单文件。不提供默认文件或回退机制。

白名单文件结构如下：

containers:
  - name: container_name
    description: "人类可读的描述"
    can_restart: true|false

规则：

• 绝对禁止对不在白名单中的容器执行 Docker 操作
• 绝对禁止重启 can_restart: false 的容器
• 若请求的容器不在白名单中，回复："容器 <name> 不在白名单中。可用容器列表： <list>"

允许的命令

仅允许使用以下 Docker 命令：

禁止的命令

绝对禁止执行以下命令：

docker rm, docker stop, docker kill, docker exec, docker run, docker pull, docker build, docker push, docker network, docker volume, docker image, docker system, docker compose

状态报告流程

当用户请求状态报告时，请按以下步骤执行：

第一步：解析时间范围

将用户输入的时间描述转换为 --since 参数值：

• "за последний час" / "last hour" → 1h
• "за сегодня" / "today" → 24h
• "за 30 минут" / "30 minutes" → 30m
• "за неделю" / "last week" → 168h
• 未指定时间范围 → 默认为 1h
• 最大限制： 168h（7天）。若用户请求更长时间，则截断至 168h 并告知用户。

第二步：收集数据

所有 docker 命令必须使用 timeout 30 包裹，防止命令挂起。

# 状态 + 启动时间 + 重启次数
timeout 30 docker inspect <name> | jq '.[0] | {Status: .State.Status, StartedAt: .State.StartedAt, RestartCount: .RestartCount, Health: .State.Health.Status}'

# 资源使用情况
timeout 30 docker stats --no-stream --format '{{json .}}' <name>

# 获取日志（最多 5000 行，用于分析）
LOG_OUTPUT=$(timeout 30 docker logs --since <period> --tail 5000 <name> 2>&1)

# 错误与警告数量统计（快速分析）
echo "${LOG_OUTPUT}" | grep -ci 'error\|exception\|fatal\|traceback'
echo "${LOG_OUTPUT}" | grep -ci 'warn'

# 最近的错误（最多 10 条唯一记录）
echo "${LOG_OUTPUT}" | grep -i 'error\|exception\|fatal\|traceback' | sort -u | tail -10

第三步：输出内容脱敏

在向用户展示日志片段前，需对敏感信息进行屏蔽：

• 令牌、API 密钥、Bearer 头部
• 包含凭证的数据库连接字符串
• 密码、环境变量中泄露的密钥

检测到上述内容后，替换为 [REDACTED]。

第四步：格式化响应

使用以下模板（根据请求语言调整）：

<status_emoji> **<container_name>**

**状态:** `running`（运行时长：2d 5h 13m）
**重启次数:** 0
**CPU:** 2.3% | **内存:** 145MiB / 512MiB（28%）
**网络 I/O:** 1.2MB / 340KB | **磁盘 I/O:** 12MB / 5MB

**最近一小时日志摘要：**
- 🔴 错误数：3
- ⚠️ 警告数：12

**最近出现的错误：**
• `ConnectionRefusedError: connect to postgres:5432`
• `TimeoutError: request took >30s`

**建议：** 检查对 PostgreSQL 的访问权限

状态图标规则：

• ✅ — 运行中，无错误，资源使用率低
• ⚠️ — 运行中但有警告/错误，或资源使用率较高（CPU/RAM >80%）
• 🔴 — 已停止/正在重启/退出，或存在严重错误

重启流程

当用户要求重启容器时，请按以下步骤操作：

1. 验证容器存在于白名单中，且 can_restart: true
2. 确认请求是明确的（用户使用了“restart”、“重启”、“重启”等关键词）
3. 冷却期检查： 同一容器每 5 分钟内最多重启一次。若重复请求，发出警告并要求确认。
4. 审计日志记录： 执行前输出：

   [AUDIT] <ISO-timestamp> restart <container_name> requested_by=<user_id_if_available>

1. 执行命令：timeout 30 docker restart <name>
2. 等待并重试验证状态：

   for i in 1 2 3; do
     sleep 10
     STATUS=$(timeout 30 docker inspect <name> | jq -r '.[0].State.Status')
     if [ "${STATUS}" = "running" ]; then break; fi
   done

1. 若容器成功运行 → 返回成功结果并附上新的状态信息
2. 若 30 秒后仍未运行 → 报告失败，并返回最后 20 行日志：

timeout 30 docker logs --tail 20 <name> 2>&1

日志查看流程

当用户要求查看日志时：

1. 验证容器在白名单中
2. 始终使用 --tail 500 限制输出量
3. 若用户要求过滤日志（如仅显示错误），使用 grep 实现
4. 对大量输出内容进行摘要，不直接输出原始日志
5. 显示前对敏感信息进行脱敏处理（参考状态报告流程第三步）

安全注意事项

• 绝对不要将用户输入直接作为容器名称传入 shell 命令 —— 只能使用白名单中的精确匹配项
• 在管道 docker logs 时始终使用 2>&1，因为错误输出（stderr）可能包含实际日志内容
• 若 DOCKER_HOST 未设置，不得猜测地址 —— 应提示用户："DOCKER_HOST 未配置。请设置此环境变量以指向 docker-socket-proxy 端点。"
• 若 Docker 命令因连接错误失败 —— 应告知用户：docker-socket-proxy 可能已宕机