certd/AGENTS.md

Certd 开发 Agent 上下文

这个文件是给在本仓库工作的开发 agent 看的常驻项目说明。后续会话进入仓库后，应先读取它，再按任务需要查看具体代码，避免每次都重新全量扫描项目。

项目用途

Certd 是一个支持私有化部署的 SSL/TLS 证书自动化管理平台。它提供 Web 管理台和后端服务，用于证书申请、续期、部署、监控、通知和开放 API 集成。

它不只是一个简单的 ACME 客户端。项目的核心产品模型是“证书流水线”：

• 通过 ACME 申请证书
• 支持 DNS-01、HTTP-01、CNAME 代理以及各类服务商集成来完成域名验证
• 支持将证书转换或导出为 pem、pfx、der、jks、p7b 等格式
• 支持把证书部署到主机、Nginx、Kubernetes、CDN、云厂商、面板等目标
• 支持通知用户，并监控站点证书过期时间

由于系统会保存证书、云厂商凭据、SSH 信息、API Key 等敏感数据，产品定位上强烈建议私有化/本地部署。

仓库结构

这是一个 pnpm + lerna 的 monorepo。

• package.json：根脚本和 workspace 元信息
• pnpm-workspace.yaml：workspace 包匹配规则
• lerna.json：lerna-lite 配置
• docs/：VitePress 文档站
• docker/：Docker 安装和运行相关文件
• packages/core/acme-client/：ACME 协议客户端，风格接近 node-acme-client
• packages/core/basic/：共享基础工具和基础设施
• packages/core/pipeline/：流水线核心、注册表、装饰器、插件模型、上下文、服务、通知等
• packages/libs/：共享集成与辅助库，例如 server、Huawei、JDCloud、Kubernetes、iframe
• packages/plugins/plugin-lib/：通用插件辅助能力和证书相关共享代码
• packages/plugins/plugin-cert/：证书流水线插件包
• packages/pro/：商业版/专业版相关包
• packages/ui/certd-server/：后端服务
• packages/ui/certd-client/：前端 Web 管理台

后端

主要后端包：packages/ui/certd-server。

技术栈：

• Node.js、ESM、TypeScript
• MidwayJS 3
• Koa
• TypeORM
• 默认使用 better-sqlite3，同时支持 PostgreSQL 和 MySQL
• 通过 @certd/midway-flyway-js 使用类似 Flyway 的 SQL 迁移机制

重要位置：

• packages/ui/certd-server/src/config/config.default.ts：默认服务、静态文件、数据库、定时任务、认证、上传、Swagger 配置
• packages/ui/certd-server/src/config/：环境与配置加载逻辑
• packages/ui/certd-server/src/configuration.ts：Midway 应用配置、中间件注册、组件导入
• packages/ui/certd-server/src/modules/：业务模块，例如 pipeline、cert、cron、monitor、login、open API、sys、plugin、cname、notification
• packages/ui/certd-server/src/controller/：按 API 领域划分的控制器
• packages/ui/certd-server/src/plugins/：后端内置的具体服务商、部署、通知等插件
• packages/ui/certd-server/db/migration/：数据库迁移 SQL
• packages/ui/certd-server/data/：本地运行数据，例如 SQLite 数据库和生成文件
• packages/ui/certd-server/logs/：运行日志

已观察到的默认开发配置：

• HTTP 端口：7001
• HTTPS 端口：7002
• 默认 SQLite 数据库：./data/db.sqlite
• 默认文件根目录：./data/files

常用脚本：

• 根目录 pnpm run start:server：以生产模式启动后端包
• 后端 pnpm run dev：启动 Midway watch/dev 服务
• 后端 pnpm run test：运行后端 mocha 测试
• 后端 pnpm run build：构建后端并导出插件元数据

前端

主要前端包：packages/ui/certd-client。

技术栈：

• Vue 3
• Vite
• TypeScript
• Ant Design Vue
• Fast Crud
• Pinia
• vue-router
• vue-i18n
• Tailwind/Windi 相关样式工具

重要位置：

• packages/ui/certd-client/src/main.ts：前端启动入口
• packages/ui/certd-client/src/App.vue：根组件
• packages/ui/certd-client/src/api/：API 调用封装
• packages/ui/certd-client/src/router/：路由
• packages/ui/certd-client/src/store/：Pinia store
• packages/ui/certd-client/src/views/certd/：核心产品页面，例如流水线、证书、授权、监控、通知、开放 API、项目、支付、插件
• packages/ui/certd-client/src/components/：共享 UI 组件
• packages/ui/certd-client/src/locales/：国际化

常用脚本：

• 前端 pnpm dev：启动 Vite 开发服务
• 前端 pnpm build：生产构建
• 前端 pnpm tsc：类型检查
• 前端暂不跑单元测试；当前 test:unit 只是占位脚本

流水线与插件模型

项目最关键的架构概念是证书流水线。

可以从 packages/core/pipeline/src/index.ts 入手，它导出：

• core
• dt
• access
• registry
• plugin
• context
• decorator
• service
• notification

插件是核心能力，不是边缘功能。新增服务商、DNS 验证、证书部署、通知方式等能力，通常应该放在插件包里，或放在 packages/ui/certd-server/src/plugins/<plugin-name>/ 下。

后端已看到的插件类型包括：

• DNS 和注册商服务商：Aliyun、Tencent、Cloudflare、Huawei、JDCloud、AWS、Azure、Google、GoDaddy、Namesilo、Xinnet、West、UCloud、Qiniu、Upyun、Volcengine 等
• 部署目标：host、Kubernetes、Nginx Proxy Manager、APISIX、Proxmox、QNAP、Dokploy、GoEdge、各类 CDN、各类面板
• 系统/产品插件：notification、captcha、oauth、admin、plus/pro、demo/template

当修改证书申请、验证、部署或通知行为时，先判断改动属于哪里：

• ACME client 代码
• pipeline 核心抽象
• 后端 module/service/entity/controller
• 某个具体插件实现
• 前端 view/form/schema

如果只是某个服务商或部署目标的问题，不要轻易修改共享 pipeline/core 行为，除非确实是可复用的公共能力。

ACME / EAB 注意事项

• 公共 EAB（尤其是 Google EAB）可能只能创建一次 ACME 账号。要跨用户复用公共 EAB，应保存并复用同一个 ACME account private key；accountUrl 如果存到 userContext 里，只能视为当前用户缓存，因为 userContext 跟用户 id 走。
• ACME 协议的 newAccount 支持 onlyReturnExisting。使用同一个 account private key 调用 newAccount({ onlyReturnExisting: true }) 可以取回已创建账号的 URL，且不会再次消费 EAB。
• 修改 EAB 的 kid 后，应重新生成绑定该 kid 的 account private key；否则应阻止继续申请并提示用户刷新账号私钥。

数据与迁移

后端使用 TypeORM 实体加 SQL 迁移。

重点查看：

• packages/ui/certd-server/src/modules/**/entity/*.ts
• packages/ui/certd-server/db/migration/*.sql

默认配置中 synchronize: false，所以涉及表结构变更时，通常应该添加或更新迁移脚本，而不是依赖 TypeORM 自动同步。

开发注意事项

• 中文 README 在部分 PowerShell 环境中可能显示乱码；README_en.md 可读性更好，且包含同样的高层项目说明。
• 初次整理时观察到当前分支为 v2-dev。
• 根包管理器是 pnpm，不要引入 npm/yarn lockfile。
• 优先沿用现有模块、插件、服务模式，再考虑新增抽象。
• packages/ui/certd-server/data/、logs/、生成的 metadata/dist 等通常视为运行时或构建产物，除非任务明确要求处理它们。
• 注意本地数据和配置里可能包含凭据、证书材料等敏感信息。
• 本仓库代码注释优先使用中文，尤其是解释业务规则、兼容逻辑、协议细节和隐藏风险时；除非文件已有明确英文注释风格或引用外部英文术语，否则不要新增英文说明性注释。

插件开发技能

仓库内置了 Certd 插件开发技能，供 Trae 和 Codex 共用：

• Trae 入口：.trae/skills
• Codex 入口：.codex/skills

其中 .codex/skills 是指向 .trae/skills 的目录链接，不要复制出第二份技能内容。更新技能时只维护 .trae/skills 下的原始文件，Codex 会通过 .codex/skills 读取同一份内容。

当前技能包括：

• access-plugin-dev：开发 Access 授权插件
• dns-provider-dev：开发 DNS Provider 插件
• task-plugin-dev：开发 Task 部署任务插件
• plugin-converter：将插件转换为 YAML 配置

做插件相关任务时，先读取对应技能目录下的 SKILL.md，再进入具体实现。若用户在插件开发中指出更好的做法，应总结并更新对应技能。

快速定向命令

进入项目后，优先使用这些有目标的读取命令，而不是立刻全仓库扫描：

Get-Content -Encoding utf8 package.json
Get-Content -Encoding utf8 pnpm-workspace.yaml
Get-Content -Encoding utf8 lerna.json
Get-Content -Encoding utf8 README_en.md -TotalCount 180
Get-Content -Encoding utf8 packages\ui\certd-server\package.json
Get-Content -Encoding utf8 packages\ui\certd-client\package.json
Get-ChildItem packages\ui\certd-server\src\modules
Get-ChildItem packages\ui\certd-server\src\plugins
Get-ChildItem packages\ui\certd-client\src\views\certd

本仓库 Agent 工作方式

• 先读本文件，再按用户任务查看相关 package/module。
• 在 PowerShell 中读取中文、Markdown、locale、文档类文件时，显式使用 Get-Content -Encoding utf8；如果仍然显示乱码，再先执行 [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new() 后重试。
• 做后端任务时，先定位 packages/ui/certd-server/src/modules 下的模块，以及相关 entity/service/controller。
• 做前端任务时，先定位 packages/ui/certd-client/src/views/certd 下的页面，再找对应 src/api。
• 做服务商、DNS、部署、通知相关任务时，先看 packages/ui/certd-server/src/plugins，再看 packages/plugins/plugin-lib 里的共享辅助能力。
• 做数据库结构变更时，添加或更新迁移脚本，不要依赖 TypeORM 自动同步。
• 实现新功能或修复行为缺陷前，先补对应单元测试，并先运行测试确认它处于失败状态；再实现功能或修复代码，反复运行聚焦单元测试直到通过。若某项改动确实不适合先写单元测试，应在回复中说明原因和替代验证方式。
• 后补单元测试时，应先基于对正确行为的实际预期编写测试，而不是为了迎合现有实现改写预期；如果运行后出现红灯，且通过测试需要修改已有实现，应先向用户确认这是确实的 bug，还是原本需求/既有行为就是如此；确认后再修改原始实现，避免把测试补充变成未经确认的行为改动。
• 后端纯单元测试用例放在 src 目录内，并尽量与被测文件相邻，例如 src/utils/random.test.ts；对应 test:unit 只跑 src/**/*.test.ts，构建/打包配置应排除这些 *.test.ts 文件。
• 单元测试需要 mock ESM 静态 import 时，优先使用 esmock，不要为了测试把业务代码改成构造函数注入或把逻辑挪到调用方；各包 test:unit 脚本应显式设置 NODE_ENV=unittest。
• 单个 monorepo 包运行单元测试时，优先使用 corepack pnpm --dir <包目录> test:unit，例如 corepack pnpm --dir packages\ui\certd-server test:unit、corepack pnpm --dir packages\core\basic test:unit、corepack pnpm --dir packages\plugins\plugin-lib test:unit；也可以用包名过滤，例如 corepack pnpm --filter @certd/ui-server test:unit。前端 packages\ui\certd-client 暂时不跑单元测试。
• 前端 TS/Vue/locale 等文件改动后，优先只对本次改动文件运行项目现有自动格式化/修复；Windows/PowerShell 下 Prettier 已验证可用命令为 packages\ui\certd-client\node_modules\.bin\prettier.cmd --write <files>，ESLint 可用命令为 packages\ui\certd-client\node_modules\.bin\eslint.cmd --fix <files>；不要为了格式化无关文件而扩大 diff。项目保留了 tslint 依赖，但当前主要使用 ESLint + Prettier。
• 优先对改动包运行聚焦的测试或类型检查；只有跨包影响明显时再考虑全 monorepo 构建。