mingmingtang/ops-agent repository overview

⁠Ops Agent · 运维智能体

把"让模型帮我运维"这件事做得可控:模型负责规划与生成命令,真正的执行权始终握在你手里。

你: 检查 web-prod-1 的磁盘使用率,>80% 的分区列出最大的 5 个目录
Agent: 计划 → 生成命令 `df -h`(只读,自动执行)
       → 生成命令 `du -sh /var/* | sort -rh | head -5`(等待你审批)
你: [批准]
Agent: 执行 → 汇总结论

⁠💡 项目背景

⁠🎬 视频演示

• 🎥 功能演示:https://www.bilibili.com/video/BV16VJ56bEo5/⁠
• 🛠️ 部署教程:https://www.bilibili.com/video/BV1LpJ56pERU/⁠

⁠✨ 特性

• 🤖 自然语言运维 —— LangGraph 编排的 Plan-and-Execute Agent,自动拆解任务、生成命令、反思结果。
• 🛡️ 命令分级护栏 —— 命令自动分级为 只读 / 变更 / 危险,只读可放行,变更与危险默认逐条人工审批。
• 🙋 人工审批门 (Human-in-the-loop) —— 基于 LangGraph interrupt(),审批前任务挂起、审批后续跑,可按会话开启「本会话免确认」。
• 🖥️ 内置 SSH 终端 —— Web 控制台自带多 Tab 交互式终端,Agent 操作之余也能自己上手敲。
• 🧩 多模型供应商 —— 内置 OpenAI / Anthropic / 通义千问(Qwen) / MiniMax / DeepSeek,后台即可切换默认模型。
• 🔐 凭证加密落库 —— SSH 私钥/密码等敏感凭证用 Fernet 加密存储。
• 📋 全量审计 —— 每次命令执行、每次审批都落库可追溯。
• 🔑 单用户登录认证 + 多会话并行隔离 + 刷新保持会话 + 移动端适配。

⁠🚀 快速开始(Docker,推荐)

镜像已发布到 Docker Hub:mingmingtang/ops-agent⁠。

⁠1. 生成凭证加密主密钥

所有入库的敏感凭证都用这个 Fernet 密钥加密,必须设置且妥善保管(丢了就解不开已存的凭证)。直接用镜像生成一个:

docker run --rm mingmingtang/ops-agent \
  python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

⁠2. 启动容器

docker run -d --name ops-agent \
  -p 8000:8000 \
  -e SECRET_ENCRYPTION_KEY="把上一步生成的密钥粘贴到这里" \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD="换成你自己的强密码" \
  -v ops-agent-data:/app/data \
  --restart unless-stopped \
  mingmingtang/ops-agent:latest

打开 **http://localhost:8000**,用上面的用户名/密码登录即可。数据(SQLite)持久化在⁠ ops-agent-data 卷里,容器重建不丢。

⁠3. 用 docker compose(可选)

仓库根目录已带 docker-compose.yml(默认拉取已发布镜像):

# 先把密钥写进环境变量或 .env 文件
echo "SECRET_ENCRYPTION_KEY=$(docker run --rm mingmingtang/ops-agent python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')" > .env
echo "AUTH_USERNAME=admin"            >> .env
echo "AUTH_PASSWORD=换成你自己的强密码" >> .env

docker compose up -d

⁠🧭 使用教程

登录控制台后,顶部有几个标签页,按下面顺序配置一遍即可开始干活。

⁠① 模型 —— 接一个大模型

进入 模型 标签 → 新增一个供应商,例如:

保存后勾选「设为默认」。支持 openai / anthropic / qwen / minimax / deepseek,后四类走 OpenAI 兼容协议,必要时可自定义 base_url。

⁠② 服务器 —— 登记要操作的机器

进入 服务器 标签,填写 host / port / 用户名,以及认证方式:

• SSH 私钥:先到 SSH秘钥 标签上传/粘贴私钥,再在服务器里选用;
• 密码:直接填密码。

凭证保存时会用 Fernet 加密。填好后点「测试连通性」确认能连上。

⁠③ 对话 —— 下达运维任务

回到 对话 标签:

1. (可选)在「操作对象」里勾选本次允许操作的服务器,不勾选=允许全部。
2. 输入任务,例如「检查 web-prod-1 的磁盘使用率,>80% 的分区列出最大的 5 个目录」。
3. Agent 会规划并生成命令:
   • 只读命令 自动执行;
   • 变更/危险命令 弹出审批框,展示将要执行的命令,点「批准」才执行,「拒绝」则跳过。
4. 信任当前任务、想少点几次确认?勾选「⚡ 本会话所有命令无需确认」即可在本会话内放行(立即生效)。
5. 需要自己动手时,右侧 终端 面板可直接开一个该服务器的交互式 SSH 终端。

⁠④ 审计 —— 回看做过什么

审计 标签按时间线记录了每条执行过的命令、风险等级与审批结果,便于复盘和合规追溯。

⁠🛠️ 配置项(环境变量)

⁠💻 从源码运行(开发)

需要 Python 3.12+ 与 uv⁠;如需 stdio 方式的云 MCP 还需 Node.js(npx)。

git clone https://github.com/<your-org>/ops-agent.git
cd ops-agent
uv venv && source .venv/bin/activate
uv pip install -e .

cp .env.example .env
# 编辑 .env:生成并填入 SECRET_ENCRYPTION_KEY,设置 AUTH_PASSWORD
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

python -m app.main          # 默认 http://localhost:8000(开发模式带热重载)

⁠🏗️ 架构一览

⁠🔌 API 速览

控制台所有操作都是这些 HTTP 接口的封装(启用认证后需先登录拿到会话 Cookie):

⁠⚠️ 安全须知

再次强调:不建议用于生产环境。即便只是在测试/内网环境体验,也请务必:

• 设置强 AUTH_PASSWORD,不要把端口裸暴露到公网(建议放在反向代理 + HTTPS 之后,或仅限内网/VPN)。
• 妥善保管 SECRET_ENCRYPTION_KEY,丢失将无法解密已存凭证。
• 给 Agent 使用的 SSH 账号按最小权限配置。
• 生产环境保持「危险命令强制审批」开启,谨慎使用「本会话免确认」。

⁠🧱 生产化 TODO(脚手架未做)

工程化 / 安全硬化

• checkpointer 换 PostgresSaver(当前默认进程内 MemorySaver)
• 正式鉴权 / RBAC / 多用户隔离(当前为单用户登录)
• SSH known_hosts 主机指纹校验(当前为 None)
• 审批超时、guardrail 规则后台可配 / 用小模型打风险分
• 密钥改用 KMS / Vault 托管

能力扩展

• 云资源管理(基于多云 MCP,纳管 ECS / OSS / 安全组等资源)
• 监控管理(对接 Prometheus / Zabbix 等,告警查询与处置闭环)
• 路由交换管理(网络设备配置/排障,如交换机、路由器、防火墙)

⁠📄 License

MIT(如仓库尚无 LICENSE 文件,请按需补充)。欢迎 Issue / PR。