AI App Ops Tools

面向运维工程师的 AI 驱动自然语言运维终端 —— 用一句话统一操作 Linux、Windows 等异构主机。

项目背景

日常运维中我们经常面对：

• 多种操作系统：Windows / Ubuntu / CentOS / Debian / macOS …
• 不同的命令体系：df -h vs Get-PSDrive、systemctl restart vs Restart-Service、apt vs yum vs dnf …
• 重复劳动：日常巡检、批量诊断、应用部署，过程难以沉淀

本项目尝试用 AI + 跨 OS 意图模板 这一组合，把"记住命令"的负担交给工具，让运维人员只关心"做什么"，并把每一次操作沉淀为可复用的知识资产。

核心特性

• 🗣️ 自然语言操作：基于 Claude Function Calling，用一句话完成跨主机操作
• 🛡️ 三级风险闸门：READ 自动 / WRITE 需确认 / DESTRUCTIVE 默认禁用
• 🌐 统一异构 OS：同一意图（如 check_disk_usage）在 Linux/Windows/macOS 下自动路由到不同实现
• 📜 意图模板库：所有命令以 YAML 形式版本化管理，是项目的核心知识资产
• 🔌 多种连接器：SSH（Linux/Unix）、WinRM（Windows）、Local（本机测试）
• 📊 全量审计日志：谁、何时、用什么自然语言、对哪些主机执行了什么命令
• 🧱 分层架构：从单条命令到应用部署，逐层演进无需重构

架构分层

┌─────────────────────────────────────────────────────┐
│ L5  策略层   │ 灰度策略、变更窗口、AI 风险预判       │
├─────────────────────────────────────────────────────┤
│ L4  编排层   │ 多主机有序执行、依赖、健康检查门控    │
├─────────────────────────────────────────────────────┤
│ L3  应用层   │ 部署 / 升级 / 回滚 = 业务原子操作    │
├─────────────────────────────────────────────────────┤
│ L2  操作层   │ 装包 / 改配置 / 重启服务 / 拷文件    │
├─────────────────────────────────────────────────────┤
│ L1  命令层   │ df / ps / 跨 OS 命令模板  ← 当前阶段 │
└─────────────────────────────────────────────────────┘

数据流：

用户 NL 请求
   ↓
AI 编排 (Claude + Function Calling，只能调用已注册的意图)
   ↓
意图模板库 (按主机 OS 路由到对应实现)
   ↓
风险闸门 (READ/WRITE/DESTRUCTIVE)
   ↓
连接器 (SSH / WinRM / Local)
   ↓
审计日志 + 结果归一化 + AI 摘要

项目结构

ai-app-ops-tools/
├── config/
│   ├── inventory.example.yaml      # 主机清单模板
│   └── settings.yaml               # 运行时策略（含 destructive 关键字）
├── templates/                      # 意图模板库 ★ 核心知识资产
│   ├── disk.yaml
│   ├── system.yaml
│   └── service.yaml
├── apps/                           # 预留：L3 应用台账
├── playbooks/                      # 预留：L3-L4 部署剧本
├── src/ops_tools/
│   ├── config.py                   # Pydantic Settings
│   ├── inventory/                  # 主机清单 + facts 探测
│   ├── intents/                    # 意图模板加载
│   ├── connectors/                 # local / ssh / winrm
│   ├── executor/                   # 风险闸门 + 执行 + 审计
│   ├── audit/                      # SQLite 审计日志
│   ├── ai/                         # Claude 编排（Function Calling）
│   ├── api/                        # HTTP API
│   ├── main.py                     # FastAPI 入口
│   └── cli.py                      # Typer CLI
├── tests/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── .env.example

快速开始

方式一：本地开发

1. 准备 Python 环境（需要 Python ≥ 3.11）

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

2. 准备配置

cp .env.example .env
# 编辑 .env，至少填入 ANTHROPIC_API_KEY

cp config/inventory.example.yaml config/inventory.yaml
# 编辑 inventory.yaml 加入你的真实主机

3. 体验 CLI

# 列出主机
ops hosts

# 列出已注册的意图
ops intents

# 在 localhost 上执行查磁盘
ops run check_disk_usage localhost

# 写入类意图会被拦截，附命令预览
ops run restart_service localhost --params '{"service": "Spooler"}'
# 加 --confirm 才会真正执行
ops run restart_service localhost --params '{"service": "Spooler"}' --confirm

# 自然语言对话（需 ANTHROPIC_API_KEY）
ops chat "看一下 localhost 的磁盘和内存"

4. 启动 HTTP 服务

ops serve
# 访问 http://127.0.0.1:8000/docs 查看 OpenAPI 文档

---

方式二：Docker Compose 部署（推荐用于服务器侧）

1. 准备配置文件

cp .env.example .env
cp config/inventory.example.yaml config/inventory.yaml
# 按需编辑两个文件

2. 构建 + 启动

docker compose up -d --build

容器启动后会自动：

• 监听 0.0.0.0:8000（宿主机端口可在 .env 中通过 OPS_PORT 覆盖）
• 将 ./config /templates /apps /playbooks /data 以 bind mount 挂载进容器，编辑这些文件无需重建镜像
• 把审计 + SQLite 数据持久化到宿主机的 ./data 目录
• 自带健康检查（/health 端点）

3. 验证服务

# 健康检查
curl http://127.0.0.1:8000/health

# 列出主机
curl http://127.0.0.1:8000/api/v1/hosts | jq

# 列出意图
curl http://127.0.0.1:8000/api/v1/intents | jq

# 直接执行意图
curl -X POST http://127.0.0.1:8000/api/v1/run \
     -H 'Content-Type: application/json' \
     -d '{"intent":"check_disk_usage","hosts":["localhost"]}'

# 自然语言对话
curl -X POST http://127.0.0.1:8000/api/v1/chat \
     -H 'Content-Type: application/json' \
     -d '{"message":"看一下生产环境的磁盘使用率"}'

4. 进入容器执行 CLI

docker compose exec ops ops hosts
docker compose exec ops ops intents
docker compose exec ops ops chat "重启 nginx 服务"

5. 常用运维命令

docker compose logs -f ops      # 看日志
docker compose restart ops      # 重启服务
docker compose down             # 停止
docker compose up -d --build    # 改代码后重建

关于 SSH 密钥

如果要从容器内部 SSH 到目标 Linux 主机，需要把宿主机的 SSH 密钥挂进容器。在 docker-compose.yml 中解开对应的 volumes 行：

# Linux / macOS
- ${HOME}/.ssh:/root/.ssh:ro

# Windows (示例，按你的实际路径)
- C:/Users/<your-name>/.ssh:/root/.ssh:ro

⚠️ 生产环境建议使用 SSH agent forwarding、Vault、跳板机等更安全的方案，而不是直接挂载本地密钥。

升级到 PostgreSQL（可选）

SQLite 适合单机 MVP；如果要多实例部署或大量审计日志，把 docker-compose.yml 中 db 服务的注释解开，并修改 OPS_DB_URL：

OPS_DB_URL=postgresql+asyncpg://ops:changeme@db:5432/ops

并在 pyproject.toml 中加入 asyncpg。

配置说明

.env 关键项

变量	说明	默认
ANTHROPIC_API_KEY	Anthropic API Key（chat 功能必需）	空
OPS_MODEL_MAIN	主模型	claude-sonnet-4-6
OPS_MODEL_FAST	轻量任务模型	claude-haiku-4-5-20251001
OPS_DB_URL	审计数据库 URL	sqlite+aiosqlite:///./data/ops.db
OPS_AUTO_EXECUTE_WRITE	WRITE 类是否自动执行	false
OPS_ALLOW_DESTRUCTIVE	是否允许 DESTRUCTIVE	false
OPS_HOST / OPS_PORT	API 监听地址	127.0.0.1 / 8000

config/inventory.yaml 主机清单

支持 SSH（密钥 / 密码）、WinRM、Local 三种连接方式，详细字段见 inventory.example.yaml。密码字段支持 ${ENV_VAR} 形式从环境变量插值，避免明文落盘。

config/settings.yaml 运行时策略

• 默认超时
• SSH / WinRM 传输参数
• 风险策略（如自动升级为 DESTRUCTIVE 的关键字白名单）

扩展意图模板（核心知识沉淀）

在 templates/ 下新建 YAML 即可。模板示例：

intents:
  - intent: check_listening_ports
    description: 查看本机监听端口
    risk_level: READ
    params: []
    implementations:
      linux:
        command: "ss -tlnp || netstat -tlnp"
      windows:
        command: "Get-NetTCPConnection -State Listen | Select-Object LocalAddress,LocalPort,OwningProcess | ConvertTo-Json"

设计原则：

1. 意图名要表达"意图"，而不是命令 —— check_listening_ports ✅，run_ss ❌
2. 风险等级保守标注 —— 不确定就标 WRITE，确认行为安全后再降级
3. 参数显式声明 —— 模板里通过 params 列出，便于 AI 理解和参数校验

每加一个意图，AI 都能立刻自然语言调用 —— 意图模板库就是你的运维知识图谱。

CI/CD（Gitea Actions）

项目自带 .gitea/workflows/build-and-push.yml，会构建 Docker 镜像并推送到 git.hty1024.com/hty1024/ai-app-ops-tools。

触发方式

触发	产生的 tag
push 到 main	main、sha-<短哈希>、latest
push 语义化版本 tag（如 v1.2.3）	1.2.3、1.2、sha-<短哈希>
在 Gitea Web 上点 Run workflow（workflow_dispatch）	默认 tag + 可选自定义 tag

准备工作（一次性）

1. 注册 Gitea Actions Runner（如未注册）：在仓库 → Settings → Actions → Runners 获取注册命令
2. 创建 Access Token：用户头像 → Settings → Applications → Generate Token，勾选 write:package
3. 在仓库 Secrets 添加：仓库 Settings → Actions → Secrets → 新增名为 REGISTRY_TOKEN，值为上一步生成的 token
4. 打开镜像仓库：Gitea 默认启用 Packages，无需额外操作；首次 push 后会自动在 Packages 里出现

拉取镜像示例

# 在使用镜像的机器上登录
docker login git.hty1024.com -u <your-user> -p <your-token>

# 拉取
docker pull git.hty1024.com/hty1024/ai-app-ops-tools:latest

# 或在 docker-compose.yml 中替换 build: . 为：
# image: git.hty1024.com/hty1024/ai-app-ops-tools:latest

手动触发

在 Gitea Web 进入仓库 → Actions → 选择 Build and Push Docker Image → 点 Run workflow，可选填入自定义 tag。

安全模型

设计	防护目标
LLM 不能生成 shell，只能调用已注册意图	防幻觉、防注入
参数通过 shlex.quote 转义	命令注入
三级风险闸门 + 渲染后再分级	误操作放大
全量审计日志（含原始 NL 输入）	责任追溯
inventory.yaml 被 git 忽略	凭据泄漏
密码字段支持 ${ENV_VAR} 插值	明文落盘

⚠️ 当前版本面向受信任的内部使用场景；如对外暴露 API 必须叠加认证（OIDC / mTLS）和网络隔离。

路线图

• L1 命令层 — 跨 OS 自然语言查询（MVP，当前阶段）
• L2 操作层 — 服务启停、装包、改配置（部分已就位）
• L3 应用层 — 单应用部署 / 升级 / 回滚（应用台账 + 部署剧本）
• L4 编排层 — 灰度、滚动、健康检查门控、多应用依赖
• L5 策略层 — 变更窗口、AI 变更风险预判

License

MIT