企业官网建设流程全解析

Oracle Skill Console：把 170+ 官方技能变成"告警来了直接给答案"的控制台

承接系列文章《Oracle RAC 21.3 双节点 Docker Desktop 部署指南》《Oracle RAC 21.3 双节点监控与打包实战》，本文单独介绍监控栈里最有"想法"的一个组件——Skill Console（技能控制台，端口 8090）。

项目完整代码：https://github.com/dk843108982/oracle-monitoring

0. 背景：984 个技能文件，怎么用？

Oracle 官方开源了技能库 oracle/skills（984 个 Markdown，覆盖 DBA / 开发 / 迁移 / AI 全部场景）。技能是全的，但问题也来了：遇到一个具体问题（比如"表空间告警了"），该看哪几个文件？按什么顺序看？看完了 SQL 怎么抄？

Oracle 官方博客给过一个思路：“Route, Don’t Flood”——不要淹没在技能海里，先路由到最相关的那几个技能。本项目把这个思路落地成了一个可直接访问的 Web 控制台：

http://localhost:8090 （Oracle Skill Console）

它把"技能库"变成了一套四合一路由中心 + 告警联动闭环：

• 🗺 技能地图：路由表可视化，SQL 一键复制
• 🧭 按角色路由：官方推荐路径（DBA / 开发 / AI / 迁移）
• 🎯 按任务诊断：多步技能序列 +一键生成诊断手册
• 🔔 告警联动：Prometheus 告警 → 技能文件映射表

1. 总览：顶部状态栏实时聚合监控状态

打开页面，第一眼看到的是顶部状态栏——它不只是一张静态页面，而是每 15 秒轮询采集器与 Prometheus，实时聚合整个监控栈的状态：

• 采集器 UP / DOWN：oracle-collector（端口 9161）是否在线
• oracle_up：数据库实例探活结果
• 告警 FIRING / PENDING 计数：Prometheus 当前有多少条告警在触发/等待
• 表空间警告：使用率 ≥85% 的表空间实时列出

截图时刻的真实状态：采集器 UP、告警FIRING 7 / PENDING 4、表空间警告 SYSTEM 97.9% / SYSAUX 95.1%——全部来自正在运行的 Docker 监控栈，不是写死的演示数据。

2. 技能地图：路由表可视化 + SQL 一键复制

第二个亮点是"技能地图"Tab——它把db/SKILL.md里的Category Routing 路由表自动解析成三栏界面：

选中任意技能，右侧立即渲染官方技能的结构化详情：

• 📌 版本说明（19c / 21c / 23ai / 26ai 兼容性提示）
• 章节标签（Overview / Best Practices / Common Mistakes…）
• 诊断 SQL 块（每条带"复制"按钮，一键抄走）
• 最佳实践清单
• 常见坑清单（必须规避）

以db/admin/dataguard.md为例，一次渲染出17 条 Data Guard 诊断 SQL（CONVERT TO SNAPSHOT STANDBY、LOG_ARCHIVE_DEST_2、MANAGED STANDBY RECOVERY…），全部来自官方技能库原文，点一下"复制"就能贴进 DBA 的终端。

3. 按角色路由：官方推荐路径

“技能地图"回答"这个文件讲什么”，“按角色路由"回答"我这个角色该按什么顺序学”。控制台内置了 4 个角色的推荐路径：

• 🛠DBA / 数据库运维：performance（explain-plan → wait-events → optimizer-stats → awr-reports）→ monitoring（space-management / alert-log-analysis / top-sql-queries）→ security
• 💻应用开发工程师：frameworks（Spring JPA / Django / SQLAlchemy / MyBatis）→ appdev（JSON / Spatial / Text / 连接池）
• 🤖AI 工程师：agent（schema-discovery → destructive-op-guards → idempotency-patterns）→ features（ai-profiles → vector-search → dbms-vector）
• 🚚迁移负责人：migrations（migration-assessment → migrate-* → 割接策略）→ devops（schema-migrations / EBR / 测试）

每个角色都写清楚了先做什么、再做什么、为什么这个顺序——比如"先读真实执行计划，计划正常再查等待事件，估算偏差先修统计信息"，这是把官方技能库的经验沉淀成了可直接照做的 SOP。

4. 按任务诊断：一键生成诊断手册（含 25 条官方 SQL）

这是最能体现"工具价值"的功能：不用自己翻技能库，填个上下文，直接出诊断手册。

页面内置了 5 条官方多步任务流程（慢查询诊断、表空间告警处理、RAG on Oracle、Agent 安全变更、SQLcl MCP 接入），下方是"一键执行技能诊断"：

1. 选择诊断类型（8 类：表空间 / Alert 日志 ORA / 慢 SQL / 等待事件 / 实例失联 / 内存 / AWR / ASH）
2. 输入告警上下文 JSON（如{"tablespace":"USERS","used_pct":92}）
3. 点"运行诊断 →"

后端复用采集器里的skills_engine，把告警类型路由到官方技能文件，自动拼装出一份完整的技能诊断手册并落盘collector/reports/：

【Oracle 技能诊断手册】表空间空间告警诊断 告警类型 : tablespace 技能来源 : oracle/skills -> db/monitoring/space-management.md 技能摘要 : 基于 DBA_TABLESPACE_USAGE_METRICS 评估使用率、自动扩展、HWM 与碎片， 按阈值分级 (>=95 CRITICAL / >=85 WARNING / >=75 WATCH) 给出处理方案。 告警上下文 : {"tablespace": "USERS", "used_pct": 92} [诊断 SQL] 共 25 条（来源: 官方技能库） --- SQL 1 --- DBA_TABLESPACE_USAGE_METRICS 全量使用报告 --- SQL 2 --- 80% 以上表空间告警清单 ...

手册生成即落盘，左侧"诊断报告历史"可随时回看（实测库里已经积累了 OracleTablespaceCritical / OracleOptimizerStatsStale / OracleInstanceDown / OracleBufferCacheHitRatioLow 等一批真实报告）。这意味着：告警来临时，答案文件已经自动存在磁盘上了。

5. 告警联动（核心）：Prometheus 告警 ↔ 技能文件映射表

最后一个 Tab 把"监控"和"技能"真正串了起来——告警联动：

配合系列文章里的40 条 Prometheus 告警规则 + alert-handler，完整闭环是：

Prometheus 告警触发 → WatchAlert / Alertmanager WebHook → alert-handler（端口 8080）按 ALERT_SKILL_MAP 找到技能文件 → 生成技能诊断手册 reports/<告警名>.txt → Skill Console 顶部实时显示 FIRING / PENDING，映射表告诉你"该看哪个技能"

也就是说：收到 OracleOptimizerStatsStale 告警，手册目录里就自动多出一份 optimizer-stats 技能的诊断指南——从"告警"到"答案"不需要人肉搜索。

6. 实现：一个 Python 文件 + 一个静态页

整个控制台只有两个文件，零依赖框架：

• skill-console/server.py（约 17KB）：Python 标准库 HTTP 服务 + 技能索引 + 诊断引擎复用
• skill-console/index.html（约 16KB）：单页前端（原生 JS，四个 Tab + 状态轮询）

启动方式（一行）：

py-3.12 skill-console/server.py--port 8090--repo <oracle-skills 绝对路径>--reports-dircollector\reports

内置 API 一览：

实测中顺手修掉一个 bug：官方db/SKILL.md的 Directory 列带尾部斜杠（如db/admin/），前端拼接dir + "/"会变成db/admin//导致技能列表永远为空——在解析时rstrip("/")即可，修复后 19 个分类 170+ 技能文件全部正常索引。

6.1 部署方式（两种）

方式 A：命令行启动（调试推荐）

py-3.12 skill-console\server.py `--port 8090 `--repo <repo>\oracle-skills `--reports-dir<repo>\collector\reports `--collector http://127.0.0.1:9161 `--prometheus http://127.0.0.1:9090

启动后打印技能索引: 170 个技能 / 19 个分类即成功。

方式 B：随监控栈一键启动

start-all.ps1的 8090 段（91-94 行）已内置上述命令，与其余 10 个容器一起拉起。

6.2 工作原理（架构，零第三方依赖）

Handler (BaseHTTPRequestHandler) ├─ GET /api/skills /api/skill /api/routes /api/startpoints │ /api/search /api/stats /api/alertmap /api/reports /api/status └─ POST /api/run （一键执行技能诊断） │ ┌──────┼──────────┐ ▼ ▼ ▼ SkillsIndex ConsoleState SkillsEngine(collector 复用) 解析路由表 聚合采集器/告警 ALERT_ROUTES 14 类 遍历 984 md 动态告警映射16条 runbook() 生成手册

• 索引构建（启动一次）：解析db/SKILL.md路由表得 19 分类，遍历db/**/*.md得 170+ 技能，提取 SQL 块 / 章节 / 最佳实践 / 常见坑 / 版本说明。
• 状态聚合（前端每 15s）：/api/status同时探测采集器（9161）与 Prometheus（9090）。
• 告警联动：ALERT_SKILL_MAP（16 条告警名）×ALERT_ROUTES（14 类诊断路由）动态生成/api/alertmap，当前 FIRING 的告警前端红色高亮。
• 一键诊断：POST/api/run带alert_type，SkillsEngine.runbook()组装官方 SQL 诊断手册落盘reports/。

6.3 与监控栈的联动闭环

oracle-collector (9161) → Prometheus (9090，40 条告警规则) → WatchAlert (9002) → WebHook → alert-handler (8080，ALERT_SKILL_MAP) → Skill Console (8090) → POST /api/run → 诊断手册 reports/（官方 SQL 可直接抄）

6.4 API 一览（v2 增强后 10 个）

7. 与官方 oracle/skills 能力核对（v2）

对照官方db/SKILL.md（19 分类路由表 / 13 个 Key Starting Points / 8 条 Common Multi-Step Flows）逐项核对：

仍可扩展（未做）：技能交叉引用图、多技能库切换、告警手册按严重级别分页、技能 diff 对比。

8. 增强一览（v2：页面更详细、功能更全）

• 🔍全文检索 Tab：搜 170+ 技能正文，标题 + 文件路径 + 命中片段，点击直达技能地图定位（实测tablespace命中 39 个技能文件）。
• 📚技能库统计栏：顶部实时显示 170 技能 / 19 分类 / 1748 条诊断 SQL / 737 最佳实践 / 16 告警映射 / 9 任务流。
• 🚀官方起点横幅：13 个 Key Starting Points 常驻顶部。
• 🔔告警联动 16 条 + 实时高亮：当前 FIRING 的告警红色高亮，每 30s 刷新。
• 🎯任务流 5 → 9 条、⚡一键诊断 8 → 14 类。

9. 总结

Skill Console 的价值可以浓缩成一句话：把"984 个技能文件"从资料库变成"可路由、可执行、可联动"的运维工具。

• 想查技能 → 技能地图，SQL 一键复制
• 想学路线 → 按角色路由，官方顺序照做
• 想处理告警 → 一键诊断生成手册，报告落盘可回看
• 想自动化 → 告警联动，Prometheus 告警自动映射技能文件

完整代码（含部署 / 监控 / 打包三篇配套文档与全部脚本）已开源：

https://github.com/dk843108982/oracle-monitoring

欢迎评论区交流～（首发于 CSDN，转载注明出处）