name: edgion-skills description: Root navigation for the Edgion knowledge base. Read this first, then drill into the relevant subtree.
Edgion Skills
Rust + Pingora + Gateway API 的 Kubernetes 网关。Controller–Gateway 分离，gRPC 配置同步。 支持 HTTP/1.1、HTTP/2、gRPC、TCP、UDP、TLS、WebSocket，含插件系统、负载均衡、TLS/mTLS。
导航规则
- 渐进式披露：本文件 → 分类 SKILL.md → 具体文件。只加载当前任务需要的最小子树。
- 三层定位：
- 理解架构（内部怎么实现） →
01-architecture/ - 查功能/配置（怎么用/怎么配） →
02-features/ - 写代码（编码规范） →
03-coding/
- 理解架构（内部怎么实现） →
- 跨领域任务：修改一个资源的 Handler 通常需要 architecture（理解处理流程）→ features（功能/Schema 参考）→ coding（编码约束）→ testing（验证），按需逐层加载。
- 资源相关任务——两个目录按编号对齐，职责互补：
- 01-architecture/05-resources/ — 内部实现：Handler 流程、requeue 关联、匹配引擎、源码位置
- 02-features/03-resources/ — 外部契约：YAML Schema、字段类型与默认值、配置示例
- 改代码通常两边都要看：02 查 Schema 确认字段定义，01 查实现确认处理逻辑
快速定位
| 你想了解… | 直接入口 |
|---|---|
| 系统架构 — Controller/Gateway/Ctl 三 bin 关系、内部模块、开发指南 | 01-architecture/SKILL.md |
| 二进制启动与部署 — CLI 参数、部署模式 | 02-features/01-binary-and-deployment/ |
| TOML 配置 Schema — Controller/Gateway 配置 | 02-features/02-config/ |
| 资源功能 Schema — Gateway/Route/TLS/Plugin/Backend/LinkSys | 02-features/03-resources/ |
| 可观测性 — Access Log、Metrics、协议日志 | 02-features/04-observability/ |
| 注解参考 — 所有 edgion.io/* 键 | 02-features/05-annotations/ |
| 编码规范 — 日志 ID、日志安全、可观测性 | 03-coding/SKILL.md |
| 集成测试 — 架构、运行、新增用例 | 05-testing/01-integration-testing.md |
| 全局 Review — 安全/正确性/可观测性检查清单 + 已关闭误报条目 | 10-fully-review/SKILL.md |
| 用户文档规范 — 撰写/审阅 docs/ 文档的写作规范 | 11-doc/SKILL.md |
| CI/发布自动化 — GitHub Release、tag 推送、Docker 镜像、发布说明文件位置 | 09-misc/cicd/02-github-workflow.md |
Center 联邦持久化 — SQLite controllers 表、CenterDb、database 配置（PM 数据已改用反向 Watch，无 SQLite 缓存） | 09-misc/center-db.md |
| Center 反向 Watch 架构 — CenterWatchCache、CenterMetaDataStore、federation gRPC 双向流 PM 数据流 | 09-misc/center-db.md#pluginmetadata-数据流反向-watch-架构 |
| 开发部署热替换 — 原生镜像 + shell loop + 交叉编译 + kubectl cp | 09-misc/03-dev-deploy-hot-replace.md |
架构内部细粒度定位（Controller/Gateway/Link/资源/插件开发/路由匹配等）见 01-architecture/SKILL.md。
关键约束（必读，违反会引入运行时 bug）
这里只列"非显而易见、代码本身看不出来、犯过错"的约束。
| 约束 | 位置 | 详情 |
|---|---|---|
| PluginConditions regex 必须在 preparse compile | conditions/types.rs, edgion_plugins/mod.rs | compiled_regex 是 #[serde(skip)]，反序列化后为 None。必须在 EdgionPlugins::preparse() 阶段调用 compile_conditions() 完成编译，否则每请求触发 Regex::new()。新增带 regex 的条件类型时，同步在 Condition::compile() 加 match 臂。详见 05-plugin-system.md §条件执行 |
| gRPC H2 grpc-status 必须放 trailers | Pingora H2 响应路径 | 放在 response headers 里 tonic 会返回 Internal(13)，必须放 trailers |
| 数据面请求/连接热路径禁止 tracing | skills/03-coding/01-log-safety.md 铁律 3 | 请求/连接处理路径只能用 access log / PluginLog / ctx.err_log / Metrics，任何 tracing:: 宏（含 debug!）都禁止。例外：配置加载路径、进程启动/关闭、pg_logging.rs access log 发送失败。插件 run_request / run_upstream_response / TLS proxy / stream proxy 全部适用。 |
目录总览
| # | 目录 | 用途 |
|---|---|---|
| 01 | architecture/ | 系统架构 + 开发指南：Controller、Gateway、gRPC 同步、资源处理、插件/资源/连接器开发 |
| 02 | features/ | 功能与配置参考：二进制部署、配置 Schema、资源功能 Schema、可观测性、注解 |
| 03 | coding/ | 编码规范：日志 ID、日志安全、可观测性（Access Log / Metrics / Tracing） |
| 04 | review/ | Review 沉淀：误报判定、可观测性审查 |
| 05 | testing/ | 测试：单元测试、集成测试、K8s 测试、专项测试 |
| 06 | tracing/ | 调试：Admin API、edgion-cli、常见问题 |
| 07 | tasks/ | 任务管理：目录规则、模板、生命周期阶段、完成检查清单 |
| 08 | kubernetes/ | Kubernetes 相关：Gateway API 兼容性、API 版本升级策略 |
| 09 | misc/ | 杂项（TLS 排查等） |
| 10 | fully-review/ | 全局 Review 指南：各维度检查清单、安全误判规则、已关闭条目 |
| 11 | 11-doc/ | 用户文档规范：目录结构、写作风格、页面模板、多语言、版本管理、Review 检查清单 |
开发生命周期速查
任务按阶段推进，每阶段加载对应 skills（详见 07-tasks/SKILL.md）：
| Phase | 做什么 | 加载 |
|---|---|---|
| 1 Analysis | 需求分析、影响评估 | 01-architecture/ |
| 2 Design | 方案设计、Schema 确认 | 01-architecture/, 02-features/ |
| 3 Implementation | 编码 | 01-architecture/（开发指南）, 02-features/（配置 Schema）, 03-coding/ |
| 4 Testing | 测试验证 | 05-testing/ |
| 5 Review | 代码审查 | 04-review/, 10-fully-review/（全局 review 或评审 AI 报告时） |
用户文档
位于 docs/，按语言分目录（en、zh-CN、ja）。完整目录树见 docs/DIRECTORY.md。
撰写或审阅用户文档时，遵循 11-doc/SKILL.md 中的写作规范。