diff --git a/.trae/skills/access-plugin-dev/SKILL.md b/.trae/skills/access-plugin-dev/SKILL.md index 71eae368b..433657230 100644 --- a/.trae/skills/access-plugin-dev/SKILL.md +++ b/.trae/skills/access-plugin-dev/SKILL.md @@ -1,204 +1,59 @@ +--- +name: access-plugin-dev +description: 用于开发 Certd 系统中的 Access 插件,存储用户第三方应用授权数据并对接实现第三方 API 接口。当用户需要创建授权插件、实现第三方API接口、添加新的授权方式或修改现有 Access 插件时触发。 +version: 1.0.0 +--- + # Access 插件开发技能 -## 什么是 Access 插件 +## 角色定义 +你是一名 Certd 插件开发专家,擅长创建和实现 Access 类型的插件,熟悉 TypeScript 编程和 Certd 插件开发规范。 -Access 插件是 Certd 系统中用于存储用户第三方应用授权数据的插件,例如用户名密码、accessSecret 或 accessToken 等。同时,它还负责对接实现第三方的 API 接口,供其他插件调用使用。 +## 核心指令 +请严格按照以下步骤执行任务: -## 开发步骤 +1. **导入必要的依赖** + - 导入 `AccessInput`, `BaseAccess`, `IsAccess`, `Pager`, `PageRes`, `PageSearch` 等必要的类型和装饰器 + - 导入 `DomainRecord` 等相关类型 -### 1. 导入必要的依赖 +2. **使用 @IsAccess 注解注册插件** + - 配置插件的唯一标识、标题、图标和描述 + - 继承 `BaseAccess` 类 -```typescript -import { AccessInput, BaseAccess, IsAccess, Pager, PageRes, PageSearch } from '@certd/pipeline'; -import { DomainRecord } from '@certd/plugin-lib'; -``` +3. **定义授权属性** + - 使用 `@AccessInput` 注解定义授权属性 + - 配置属性的标题、默认值、组件类型和验证规则 + - 对于敏感信息,设置 `encrypt: true` 进行加密 -### 2. 使用 @IsAccess 注解注册插件 +4. **实现测试方法** + - 添加测试按钮配置 + - 实现 `onTestRequest` 方法,用于测试接口调用是否正常 -```typescript -@IsAccess({ - name: 'demo', // 插件唯一标识 - title: '授权插件示例', // 插件标题 - icon: 'clarity:plugin-line', // 插件图标 - desc: '这是一个示例授权插件,用于演示如何实现一个授权插件', // 插件描述 -}) -export class DemoAccess extends BaseAccess { - // 插件实现... -} -``` +5. **实现 API 方法** + - 实现必要的 API 方法,如 `GetDomainList` + - 封装统一的 API 请求方法 `doRequest`,处理错误和日志 -### 3. 定义授权属性 +6. **遵循开发最佳实践** + - 使用 `this.ctx.logger` 输出日志 + - 统一处理错误,抛出明确的错误信息 + - 实现代码复用,避免重复逻辑 -使用 `@AccessInput` 注解定义授权属性: +## 输出规范 +- 必须包含完整的插件实现代码,包括所有必要的导入语句 +- 代码必须包含详细的注释说明,解释每个步骤的目的和实现细节 +- 提供完整的示例代码,展示插件的使用方法,包括不同类型的授权方式 +- 代码块必须使用正确的语法高亮,确保代码可读性 +- 包含开发技巧和注意事项,帮助开发者避免常见错误 +- 输出内容必须结构清晰,使用适当的标题和列表格式 -```typescript -@AccessInput({ - title: '授权方式', - value: 'apiKey', // 默认值 - component: { - name: "a-select", // 基于 antdv 的输入组件 - vModel: "value", // v-model 绑定的属性名 - options: [ // 组件参数 - { label: "API密钥(推荐)", value: "apiKey" }, - { label: "账号密码", value: "account" }, - ], - placeholder: 'demoKeyId', - }, - required: true, -}) -apiType = ''; +## 示例 -@AccessInput({ - title: '密钥Id', - component: { - name:"a-input", - allowClear: true, - placeholder: 'demoKeyId', - }, - required: true, -}) -demoKeyId = ''; +### 示例 1: 基本 Access 插件 -@AccessInput({ - title: '密钥',//标题 - required: true, //text组件可以省略 - encrypt: true, //该属性是否需要加密 -}) -demoKeySecret = ''; +#### 用户输入 +创建一个 Access 插件,用于存储第三方应用的授权信息并提供 API 接口。 - - -@AccessInput({ - title: '另外一个授权Id',//标题 - component: { - name:"access-selector", //access选择组件 - vModel:"modelValue", - type: "ssh", // access类型,让用户固定选择这种类型的access - }, - required: true, //text组件可以省略 -}) -otherAccessId; - -``` - -### 4. 实现测试方法 - -```typescript -@AccessInput({ - title: "测试", - component: { - name: "api-test", - action: "TestRequest" - }, - helper: "点击测试接口是否正常" -}) -testRequest = true; - -/** - * 会通过上面的testRequest参数在ui界面上生成测试按钮,供用户测试接口调用是否正常 - */ -async onTestRequest() { - await this.GetDomainList({}); - return "ok" -} -``` - -### 5. 实现 API 方法 - -```typescript -/** - * api接口示例 获取域名列表, - */ -async GetDomainList(req: PageSearch): Promise> { - //输出日志必须使用ctx.logger - this.ctx.logger.info(`获取域名列表,req:${JSON.stringify(req)}`); - const pager = new Pager(req); - const resp = await this.doRequest({ - action: "ListDomains", - data: { - domain: req.searchKey, - offset: pager.getOffset(), - limit: pager.pageSize, - } - }); - const total = resp?.TotalCount || 0; - let list = resp?.DomainList?.map((item) => { - item.domain = item.Domain; - item.id = item.DomainId; - return item; - }) - return { - total, - list - }; -} - -/** - * 通用api调用方法, 具体如何构造请求体,需参考对应应用的API文档 - */ -async doRequest(req: { action: string, data?: any }) { - /** - this.ctx中包含很多有用的工具类 - type AccessContext = { - http: HttpClient; - logger: ILogger; - utils: typeof utils; - accessService: IAccessService; - } - - // this.ctx.http 只有request方法 - // 方法参数 - export type HttpRequestConfig = { - skipSslVerify?: boolean; - skipCheckRes?: boolean; - logParams?: boolean; - logRes?: boolean; - logData?: boolean; - httpProxy?: string; - returnOriginRes?: boolean; - } & AxiosRequestConfig; - - - */ - const res = await this.ctx.http.request({ - url: "https://api.demo.cn/api/", - method: "POST", - data: { - Action: req.action, - Body: req.data - } - }); - - if (res.Code !== 0) { - //异常处理 - throw new Error(res.Message || "请求失败"); - } - return res.Resp; -} -``` - ---- 开发技巧:实现统一的 API 请求封装 - -**好处:** -- **代码复用**:避免在每个 API 方法中重复编写相同的 header 设置和错误处理逻辑 -- **错误处理一致**:统一捕获和处理各种错误情况,确保错误信息格式统一 -- **日志记录完善**:集中记录详细的错误信息,便于调试和问题排查 -- **接口调用简化**:调用方只需关注业务逻辑,无需关心底层请求细节 -- **易于维护**:统一修改 API 调用方式时,只需修改一处代码 - - -## 注意事项 - -1. **插件命名**:插件名称应简洁明了,反映其功能。 -2. **属性加密**:对于敏感信息(如密钥),应设置 `encrypt: true`。 -3. **日志输出**:必须使用 `this.ctx.logger` 输出日志,而不是 `console`。 -4. **错误处理**:API 调用失败时应抛出明确的错误信息。 -5. **测试方法**:实现 `onTestRequest` 方法,以便用户可以测试授权是否正常。 -6. **统一接口调用方法**:封装统一的 API 请求方法,避免在每个 API 方法调用中重复编写错误处理逻辑。 - -## 完整示例 - -### 示例 1: 通用授权插件 +#### 你的回答 ```typescript import { AccessInput, BaseAccess, IsAccess, Pager, PageRes, PageSearch } from '@certd/pipeline'; @@ -216,7 +71,7 @@ import { DomainRecord } from '@certd/plugin-lib'; }) export class DemoAccess extends BaseAccess { - /** + /** * 授权属性配置 */ @AccessInput({ @@ -262,7 +117,6 @@ export class DemoAccess extends BaseAccess { }) demoKeySecret = ''; - @AccessInput({ title: "测试", component: { @@ -282,7 +136,7 @@ export class DemoAccess extends BaseAccess { } /** - * 获api接口示例 取域名列表, + * api接口示例 获取域名列表 */ async GetDomainList(req: PageSearch): Promise> { //输出日志必须使用ctx.logger @@ -308,21 +162,10 @@ export class DemoAccess extends BaseAccess { }; } - // 还可以继续编写API - /** - * 通用api调用方法, 具体如何构造请求体,需参考对应应用的API文档 + * 通用api调用方法, 具体如何构造请求体,需参考对应应用的API文档 */ async doRequest(req: { action: string, data?: any }) { - /** - this.ctx中包含很多有用的工具类 - type AccessContext = { - http: HttpClient; - logger: ILogger; - utils: typeof utils; - accessService: IAccessService; - } - */ const res = await this.ctx.http.request({ url: "https://api.demo.cn/api/", method: "POST", @@ -339,4 +182,224 @@ export class DemoAccess extends BaseAccess { return res.Resp; } } +``` + +### 示例 2: 支持 OAuth 授权的 Access 插件 + +#### 用户输入 +创建一个支持 OAuth 授权方式的 Access 插件。 + +#### 你的回答 + +```typescript +import { AccessInput, BaseAccess, IsAccess, Pager, PageRes, PageSearch } from '@certd/pipeline'; +import { DomainRecord } from '@certd/plugin-lib'; + +/** + * OAuth 授权插件示例 + */ +@IsAccess({ + name: 'oauth-demo', + title: 'OAuth授权插件示例', + icon: 'clarity:plugin-line', + desc: '这是一个支持OAuth授权的插件示例', +}) +export class OAuthDemoAccess extends BaseAccess { + + @AccessInput({ + title: '授权方式', + value: 'oauth', + component: { + name: "a-select", + vModel: "value", + options: [ + { + label: "OAuth授权", + value: "oauth" + }, + { + label: "API密钥", + value: "apiKey" + }, + ], + }, + required: true, + }) + authType = ''; + + @AccessInput({ + title: '客户端ID', + component: { + name:"a-input", + placeholder: 'Client ID', + }, + required: true, + }) + clientId = ''; + + @AccessInput({ + title: '客户端密钥', + required: true, + encrypt: true, + }) + clientSecret = ''; + + @AccessInput({ + title: '授权回调地址', + component: { + name:"a-input", + placeholder: 'https://your-domain.com/callback', + }, + required: true, + }) + redirectUri = ''; + + @AccessInput({ + title: 'AccessToken', + required: true, + encrypt: true, + }) + accessToken = ''; + + @AccessInput({ + title: 'RefreshToken', + encrypt: true, + }) + refreshToken = ''; + + @AccessInput({ + title: "测试", + component: { + name: "api-test", + action: "TestOAuth" + }, + helper: "点击测试OAuth授权是否正常" + }) + testOAuth = true; + + /** + * 测试OAuth授权 + */ + async onTestOAuth() { + try { + // 测试AccessToken是否有效 + const result = await this.doOAuthRequest('GET', '/api/user/profile'); + this.ctx.logger.info('OAuth测试成功:', result); + return "OAuth授权测试成功"; + } catch (error) { + this.ctx.logger.error('OAuth测试失败:', error); + throw new Error('OAuth授权测试失败'); + } + } + + /** + * OAuth API请求方法 + */ + async doOAuthRequest(method: string, endpoint: string, data?: any) { + const res = await this.ctx.http.request({ + url: `https://api.oauth-demo.com${endpoint}`, + method, + headers: { + 'Authorization': `Bearer ${this.accessToken}`, + 'Content-Type': 'application/json' + }, + data + }); + + if (res.status !== 200) { + throw new Error(`API请求失败: ${res.status} ${res.statusText}`); + } + return res.data; + } + + /** + * 刷新AccessToken + */ + async refreshAccessToken() { + if (!this.refreshToken) { + throw new Error('没有提供RefreshToken'); + } + + const res = await this.ctx.http.request({ + url: 'https://api.oauth-demo.com/oauth/token', + method: 'POST', + data: { + grant_type: 'refresh_token', + refresh_token: this.refreshToken, + client_id: this.clientId, + client_secret: this.clientSecret + } + }); + + if (res.status === 200 && res.data.access_token) { + this.accessToken = res.data.access_token; + if (res.data.refresh_token) { + this.refreshToken = res.data.refresh_token; + } + return true; + } + throw new Error('刷新AccessToken失败'); + } + + /** + * 获取域名列表 + */ + async GetDomainList(req: PageSearch): Promise> { + try { + const res = await this.doOAuthRequest('GET', '/api/domains', { + search: req.searchKey, + page: req.page, + pageSize: req.pageSize + }); + + return { + total: res.total, + list: res.items.map((item: any) => ({ + id: item.id, + domain: item.domain + })) + }; + } catch (error) { + // 尝试刷新AccessToken并重试 + if (error.message.includes('401')) { + await this.refreshAccessToken(); + const res = await this.doOAuthRequest('GET', '/api/domains', { + search: req.searchKey, + page: req.page, + pageSize: req.pageSize + }); + + return { + total: res.total, + list: res.items.map((item: any) => ({ + id: item.id, + domain: item.domain + })) + }; + } + throw error; + } + } +} +``` + +## 注意事项 + +1. **插件命名**:插件名称应简洁明了,反映其功能。 +2. **属性加密**:对于敏感信息(如密钥),应设置 `encrypt: true`。 +3. **日志输出**:必须使用 `this.ctx.logger` 输出日志,而不是 `console`,参数文本化,不要传对象,否则会输出`[object Object]}`。 +4. **错误处理**:API 调用失败时应抛出明确的错误信息。 +5. **测试方法**:实现 `onTestRequest` 方法,以便用户可以测试授权是否正常。 +6. **统一接口调用**:封装统一的 API 请求方法,避免重复编写错误处理逻辑。 + +## 开发技巧 + +### 实现统一的 API 请求封装 + +**好处:** +- **代码复用**:避免在每个 API 方法中重复编写相同的 header 设置和错误处理逻辑 +- **错误处理一致**:统一捕获和处理各种错误情况,确保错误信息格式统一 +- **日志记录完善**:集中记录详细的错误信息,便于调试和问题排查 +- **接口调用简化**:调用方只需关注业务逻辑,无需关心底层请求细节 +- **易于维护**:统一修改 API 调用方式时,只需修改一处代码 ``` \ No newline at end of file diff --git a/.trae/skills/dns-provider-dev/SKILL.md b/.trae/skills/dns-provider-dev/SKILL.md index 4f8edb88a..b0cb7855c 100644 --- a/.trae/skills/dns-provider-dev/SKILL.md +++ b/.trae/skills/dns-provider-dev/SKILL.md @@ -1,163 +1,82 @@ +--- +name: dns-provider-dev +description: 用于开发 Certd 系统中的 DNS Provider 插件,在 ACME 申请证书时给域名添加 TXT 解析记录以验证域名所有权。当用户需要创建DNS提供商插件、实现DNS解析、ACME证书验证或修改现有 DNS Provider 插件时触发。 +version: 1.0.0 +--- + # DNS Provider 插件开发技能 -## 什么是 DNS Provider 插件 +## 角色定义 +你是一名 Certd 插件开发专家,擅长创建和实现 DNS Provider 类型的插件,熟悉 TypeScript 编程和 Certd 插件开发规范。 -DNS Provider 插件是 Certd 系统中的 DNS 提供商插件,它用于在 ACME 申请证书时给域名添加 TXT 解析记录,以验证域名所有权。 +## 核心指令 +请严格按照以下步骤执行任务: -## 开发步骤 +1. **导入必要的依赖** + - 导入 `AbstractDnsProvider`, `CreateRecordOptions`, `IsDnsProvider`, `RemoveRecordOptions` 等必要的类型和装饰器 + - 导入对应的 Access 插件类型 -### 1. 导入必要的依赖 +2. **定义记录数据结构** + - 定义适合对应云平台的记录数据结构 + - 至少包含 id 字段,用于后续删除记录 + +3. **使用 @IsDnsProvider 注解注册插件** + - 配置插件的唯一标识、标题、描述、图标 + - 指定对应的云平台的 access 类型名称 + - 设置排序值(可选) + - 继承 `AbstractDnsProvider` 类 + +4. **实现 onInstance 方法** + - 获取并保存对应的 Access 实例 + - 执行初始化操作 + +5. **实现 createRecord 方法** + - 解析传入的参数(fullRecord, value, type, domain) + - 记录操作开始日志 + - 调用云平台 API 创建 TXT 类型的 DNS 解析记录 + - 处理可能的错误:网络错误、API调用失败、授权失败等 + - 记录操作结果日志 + - 返回创建的记录信息,用于后续删除操作 + +6. **实现 removeRecord 方法** + - 解析传入的参数和之前创建的记录信息 + - 记录操作开始日志 + - 调用云平台 API 删除 TXT 类型的 DNS 解析记录 + - 处理可能的错误:网络错误、API调用失败、记录不存在等 + - 记录操作结果日志 + +7. **实现 getDomainListPage 方法** + - 实现获取域名列表的方法 + - 支持分页查询 + - 处理可能的错误:网络错误、API调用失败、授权失败等 + - 返回标准化的域名列表格式 + +8. **实例化插件** + - 实例化插件,确保插件被注册 + +## 输出规范 +- 必须包含完整的插件实现代码 +- 代码必须包含详细的注释说明 +- 提供完整的示例代码,展示插件的使用方法 +- 包含开发注意事项 + +## 示例 + +### 示例 1: 基本 DNS Provider 插件 + +#### 用户输入 +创建一个 DNS Provider 插件,用于在 ACME 申请证书时添加和删除 TXT 解析记录。 + +#### 你的回答 ```typescript -import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions } from '@certd/plugin-cert'; +import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions, PageSearch, PageRes, DomainRecord } from '@certd/plugin-cert'; import { DemoAccess } from './access.js'; -import { isDev } from '../../utils/env.js'; -``` - -### 2. 定义记录数据结构 - -```typescript -type DemoRecord = { - // 这里定义 Record 记录的数据结构,跟对应云平台接口返回值一样即可,一般是拿到 id 就行,用于删除 txt 解析记录,清理申请痕迹 - // id:string -}; -``` - -### 3. 使用 @IsDnsProvider 注解注册插件 - -```typescript -// 这里通过 IsDnsProvider 注册一个 dnsProvider -@IsDnsProvider({ - name: 'demo', // 插件唯一标识 - title: 'Dns提供商Demo', // 插件标题 - desc: 'dns provider示例', // 插件描述 - icon: 'clarity:plugin-line', // 插件图标 - // 这里是对应的云平台的 access 类型名称 - accessType: 'demo', - order: 99, // 排序 -}) -export class DemoDnsProvider extends AbstractDnsProvider { - access!: DemoAccess; - - async onInstance() { - this.access = this.ctx.access as DemoAccess; - // 也可以通过 ctx 成员变量传递 context - this.logger.debug('access', this.access); - // 初始化的操作 - // ... - } - - // 插件实现... -} -``` - -### 4. 实现 createRecord 方法 - -```typescript -/** - * 创建 dns 解析记录,用于验证域名所有权 - */ -async createRecord(options: CreateRecordOptions): Promise { - /** - * options 参数说明 - * fullRecord: '_acme-challenge.example.com', - * value: 一串 uuid - * type: 'TXT', - * domain: 'example.com' - */ - const { fullRecord, value, type, domain } = options; - this.logger.info('添加域名解析:', fullRecord, value, type, domain); - - // 调用创建 dns 解析记录的对应的云端接口,创建 txt 类型的 dns 解析记录 - // 请根据实际接口情况调用,例如: - // const createDnsRecordUrl = "xxx" - // const record = this.http.post(createDnsRecordUrl,{ - // // 授权参数 - // // 创建 dns 解析记录的参数 - // }) - // // 返回本次创建的 dns 解析记录,这个记录会在删除的时候用到 - // return record -} -``` - -### 5. 实现 removeRecord 方法 - -```typescript -/** - * 删除 dns 解析记录,清理申请痕迹 - * @param options - */ -async removeRecord(options: RemoveRecordOptions): Promise { - const { fullRecord, value, domain } = options.recordReq; - const record = options.recordRes; - this.logger.info('删除域名解析:', domain, fullRecord, value, record); - // 这里调用删除 txt dns 解析记录接口 - // 请根据实际接口情况调用,例如: - - // const deleteDnsRecordUrl = "xxx" - // const res = this.http.delete(deleteDnsRecordUrl,{ - // // 授权参数 - // // 删除 dns 解析记录的参数 - // }) - - - this.logger.info('删除域名解析成功:', fullRecord, value); -} -``` - -### 6. 实现 getDomainListPage 方法 -```typescript - /** - * 实现获取域名列表 - */ - async getDomainListPage(req: PageSearch): Promise> { - const pager = new Pager(req); - const res = await this.http.request({ - // 请求接口获取域名列表 - }) - const list = res.Domains?.map(item => ({ - id: item.Id, - domain: item.DomainName, - })) || [] - - return { - list, - total: res.Total, - } - } -``` - -### 6. 实例化插件 - -```typescript -// 实例化这个 provider,将其自动注册到系统中 -if (isDev()) { - // 你的实现 要去掉这个 if,不然生产环境将不会显示 - new DemoDnsProvider(); -} -``` - -## 注意事项 - -1. **插件命名**:插件名称应简洁明了,反映其功能。 -2. **accessType**:必须指定对应的云平台的 access 类型名称。 -3. **记录结构**:定义适合对应云平台的记录数据结构,至少包含 id 字段用于删除记录。 -4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`。 -5. **错误处理**:API 调用失败时应抛出明确的错误信息。 -6. **实例化**:生产环境中应移除 `if (isDev())` 条件,确保插件在生产环境中也能被注册。 - -## 完整示例 - -### 示例:通用 DNS Provider - -```typescript -import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions } from '@certd/plugin-cert'; -import { DemoAccess } from './access.js'; -import { isDev } from '../../utils/env.js'; +import { Pager } from '@certd/pipeline'; type DemoRecord = { - // 这里定义 Record 记录的数据结构,跟对应云平台接口返回值一样即可,一般是拿到 id 就行,用于删除 txt 解析记录,清理申请痕迹 - // id:string + // 这里定义 Record 记录的数据结构,跟对应云平台接口返回值一样即可 + id: string; }; // 这里通过 IsDnsProvider 注册一个 dnsProvider @@ -195,15 +114,23 @@ export class DemoDnsProvider extends AbstractDnsProvider { const { fullRecord, value, type, domain } = options; this.logger.info('添加域名解析:', fullRecord, value, type, domain); - // 调用创建 dns 解析记录的对应的云端接口,创建 txt 类型的 dns 解析记录 - // 请根据实际接口情况调用,例如: - // const createDnsRecordUrl = "xxx" - // const record = this.http.post(createDnsRecordUrl,{ - // // 授权参数 - // // 创建 dns 解析记录的参数 - // }) - // // 返回本次创建的 dns 解析记录,这个记录会在删除的时候用到 - // return record + try { + // 调用创建 dns 解析记录的对应的云端接口,创建 txt 类型的 dns 解析记录 + // 请根据实际接口情况调用,例如: + // const createDnsRecordUrl = "xxx" + // const record = this.http.post(createDnsRecordUrl,{ + // // 授权参数 + // // 创建 dns 解析记录的参数 + // }) + // // 返回本次创建的 dns 解析记录,这个记录会在删除的时候用到 + // return record + + // 模拟返回 + return { id: 'demo-record-id' }; + } catch (error) { + this.logger.error('创建DNS记录失败:', error); + throw new Error(`创建DNS记录失败: ${error.message}`); + } } /** @@ -214,40 +141,302 @@ export class DemoDnsProvider extends AbstractDnsProvider { const { fullRecord, value, domain } = options.recordReq; const record = options.recordRes; this.logger.info('删除域名解析:', domain, fullRecord, value, record); - // 这里调用删除 txt dns 解析记录接口 - // 请根据实际接口情况调用,例如: - - // const deleteDnsRecordUrl = "xxx" - // const res = this.http.delete(deleteDnsRecordUrl,{ - // // 授权参数 - // // 删除 dns 解析记录的参数 - // }) - - - this.logger.info('删除域名解析成功:', fullRecord, value); + + try { + // 这里调用删除 txt dns 解析记录接口 + // 请根据实际接口情况调用,例如: + // const deleteDnsRecordUrl = "xxx" + // const res = this.http.delete(deleteDnsRecordUrl,{ + // // 授权参数 + // // 删除 dns 解析记录的参数 + // }) + + this.logger.info('删除域名解析成功:', fullRecord, value); + } catch (error) { + this.logger.error('删除DNS记录失败:', error); + // 即使删除失败也不抛出异常,避免影响整个证书申请流程 + } } /** * 实现获取域名列表 */ async getDomainListPage(req: PageSearch): Promise> { - const pager = new Pager(req); - const res = await this.http.request({ - // 请求接口获取域名列表 - }) - const list = res.Domains?.map(item => ({ - id: item.Id, - domain: item.DomainName, - })) || [] + try { + const pager = new Pager(req); + const res = await this.http.request({ + // 请求接口获取域名列表 + }) + const list = res.Domains?.map(item => ({ + id: item.Id, + domain: item.DomainName, + })) || [] - return { - list, - total: res.Total, + return { + list, + total: res.Total, + }; + } catch (error) { + this.logger.error('获取域名列表失败:', error); + return { list: [], total: 0 }; } } } // 实例化这个 provider,将其自动注册到系统中 new DemoDnsProvider(); +``` -``` \ No newline at end of file +### 示例 2: 阿里云 DNS Provider 插件 + +#### 用户输入 +创建一个阿里云 DNS Provider 插件,用于在 ACME 申请证书时添加和删除 TXT 解析记录。 + +#### 你的回答 + +```typescript +import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions, PageSearch, PageRes, DomainRecord } from '@certd/plugin-cert'; +import { AliyunAccess } from './aliyun-access.js'; +import { Pager } from '@certd/pipeline'; + +type AliyunRecord = { + RecordId: string; +}; + +// 阿里云 DNS Provider 插件 +@IsDnsProvider({ + name: 'aliyun', + title: '阿里云DNS', + desc: '阿里云DNS提供商插件', + icon: 'clarity:plugin-line', + accessType: 'aliyun', + order: 10, +}) +export class AliyunDnsProvider extends AbstractDnsProvider { + access!: AliyunAccess; + + async onInstance() { + this.access = this.ctx.access as AliyunAccess; + this.logger.debug('阿里云Access实例初始化成功'); + } + + /** + * 创建 DNS 解析记录 + */ + async createRecord(options: CreateRecordOptions): Promise { + const { fullRecord, value, type, domain } = options; + this.logger.info('阿里云DNS: 添加解析记录', { fullRecord, value, type, domain }); + + try { + // 提取主机记录 + const hostRecord = fullRecord.replace(`.${domain}`, ''); + + // 调用阿里云 API 创建解析记录 + const response = await this.access.doRequest({ + action: 'AddDomainRecord', + data: { + DomainName: domain, + RR: hostRecord, + Type: type, + Value: value, + TTL: 600, // 10分钟 + } + }); + + this.logger.info('阿里云DNS: 解析记录创建成功', { RecordId: response.RecordId }); + return { RecordId: response.RecordId }; + } catch (error) { + this.logger.error('阿里云DNS: 创建解析记录失败', error); + throw new Error(`阿里云DNS创建解析记录失败: ${error.message}`); + } + } + + /** + * 删除 DNS 解析记录 + */ + async removeRecord(options: RemoveRecordOptions): Promise { + const { fullRecord, value, domain } = options.recordReq; + const record = options.recordRes; + this.logger.info('阿里云DNS: 删除解析记录', { fullRecord, value, domain, RecordId: record.RecordId }); + + try { + // 调用阿里云 API 删除解析记录 + await this.access.doRequest({ + action: 'DeleteDomainRecord', + data: { + RecordId: record.RecordId, + } + }); + + this.logger.info('阿里云DNS: 解析记录删除成功', { RecordId: record.RecordId }); + } catch (error) { + this.logger.error('阿里云DNS: 删除解析记录失败', error); + // 即使删除失败也不抛出异常,避免影响整个证书申请流程 + } + } + + /** + * 获取域名列表 + */ + async getDomainListPage(req: PageSearch): Promise> { + try { + const pager = new Pager(req); + const response = await this.access.doRequest({ + action: 'DescribeDomains', + data: { + PageNumber: pager.page, + PageSize: pager.pageSize, + KeyWord: req.searchKey, + } + }); + + const list = response.Domains.Domain.map((domain: any) => ({ + id: domain.DomainId, + domain: domain.DomainName, + })); + + return { + list, + total: response.TotalCount, + }; + } catch (error) { + this.logger.error('阿里云DNS: 获取域名列表失败', error); + return { list: [], total: 0 }; + } + } +} + +// 实例化插件 +new AliyunDnsProvider(); +``` + +### 示例 3: 腾讯云 DNS Provider 插件 + +#### 用户输入 +创建一个腾讯云 DNS Provider 插件,用于在 ACME 申请证书时添加和删除 TXT 解析记录。 + +#### 你的回答 + +```typescript +import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions, PageSearch, PageRes, DomainRecord } from '@certd/plugin-cert'; +import { TencentAccess } from './tencent-access.js'; +import { Pager } from '@certd/pipeline'; + +type TencentRecord = { + RecordId: string; +}; + +// 腾讯云 DNS Provider 插件 +@IsDnsProvider({ + name: 'tencent', + title: '腾讯云DNS', + desc: '腾讯云DNS提供商插件', + icon: 'clarity:plugin-line', + accessType: 'tencent', + order: 20, +}) +export class TencentDnsProvider extends AbstractDnsProvider { + access!: TencentAccess; + + async onInstance() { + this.access = this.ctx.access as TencentAccess; + this.logger.debug('腾讯云Access实例初始化成功'); + } + + /** + * 创建 DNS 解析记录 + */ + async createRecord(options: CreateRecordOptions): Promise { + const { fullRecord, value, type, domain } = options; + this.logger.info('腾讯云DNS: 添加解析记录', { fullRecord, value, type, domain }); + + try { + // 提取主机记录 + const hostRecord = fullRecord.replace(`.${domain}`, ''); + + // 调用腾讯云 API 创建解析记录 + const response = await this.access.doRequest({ + action: 'CreateRecord', + data: { + Domain: domain, + SubDomain: hostRecord, + RecordType: type, + RecordValue: value, + TTL: 600, // 10分钟 + } + }); + + this.logger.info('腾讯云DNS: 解析记录创建成功', { RecordId: response.RecordId }); + return { RecordId: response.RecordId }; + } catch (error) { + this.logger.error('腾讯云DNS: 创建解析记录失败', error); + throw new Error(`腾讯云DNS创建解析记录失败: ${error.message}`); + } + } + + /** + * 删除 DNS 解析记录 + */ + async removeRecord(options: RemoveRecordOptions): Promise { + const { fullRecord, value, domain } = options.recordReq; + const record = options.recordRes; + this.logger.info('腾讯云DNS: 删除解析记录', { fullRecord, value, domain, RecordId: record.RecordId }); + + try { + // 调用腾讯云 API 删除解析记录 + await this.access.doRequest({ + action: 'DeleteRecord', + data: { + RecordId: record.RecordId, + } + }); + + this.logger.info('腾讯云DNS: 解析记录删除成功', { RecordId: record.RecordId }); + } catch (error) { + this.logger.error('腾讯云DNS: 删除解析记录失败', error); + // 即使删除失败也不抛出异常,避免影响整个证书申请流程 + } + } + + /** + * 获取域名列表 + */ + async getDomainListPage(req: PageSearch): Promise> { + try { + const pager = new Pager(req); + const response = await this.access.doRequest({ + action: 'DescribeDomains', + data: { + Offset: (pager.page - 1) * pager.pageSize, + Limit: pager.pageSize, + Keyword: req.searchKey, + } + }); + + const list = response.Domains.map((domain: any) => ({ + id: domain.DomainId, + domain: domain.DomainName, + })); + + return { + list, + total: response.TotalCount, + }; + } catch (error) { + this.logger.error('腾讯云DNS: 获取域名列表失败', error); + return { list: [], total: 0 }; + } + } +} + +// 实例化插件 +new TencentDnsProvider(); +``` + +## 注意事项 + +1. **插件命名**:插件名称应简洁明了,反映其功能。 +2. **accessType**:必须指定对应的云平台的 access 类型名称。 +3. **记录结构**:定义适合对应云平台的记录数据结构,至少包含 id 字段用于删除记录。 +4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`,参数文本化,不要传对象,否则会输出`[object Object]}`。 +5. **错误处理**:API 调用失败时应抛出明确的错误信息。 \ No newline at end of file diff --git a/.trae/skills/plugin-converter/SKILL.md b/.trae/skills/plugin-converter/SKILL.md index 4a325d4ac..260e696f9 100644 --- a/.trae/skills/plugin-converter/SKILL.md +++ b/.trae/skills/plugin-converter/SKILL.md @@ -1,126 +1,90 @@ +--- +name: plugin-converter +description: 用于将 Certd 插件转换为 YAML 配置文件的命令行工具,支持分析单个插件文件、识别插件类型并生成对应的 YAML 配置。当用户需要生成插件配置、转换插件格式、批量处理插件或修改现有插件配置时触发。 +version: 1.0.0 +--- + # 插件转换工具技能 -## 什么是插件转换工具 +## 角色定义 +你是一名 Certd 插件开发专家,擅长使用插件转换工具将 Certd 插件转换为 YAML 配置文件,熟悉命令行工具的使用和 Certd 插件开发规范。 -插件转换工具是一个用于将 Certd 插件转换为 YAML 配置文件的命令行工具。它可以分析单个插件文件,识别插件类型,并生成对应的 YAML 配置,可以让插件分发和在线注册。 +## 核心指令 +请严格按照以下步骤执行任务: -## 工具位置 +1. **定位工具位置** + - 工具位于 `trae/skills/convert-plugin-to-yaml.js` -`trae/skills/convert-plugin-to-yaml.js` +2. **了解功能特性** + - 单个插件转换:支持指定单个插件文件进行转换 + - 批量插件转换:支持指定目录批量转换多个插件 + - 自动类型识别:自动识别插件类型(Access、Task、DNS Provider、Notification、Addon) + - 详细日志输出:提供详细的转换过程日志 + - YAML 配置生成:生成标准的 YAML 配置文件 + - 配置文件保存:自动将生成的配置保存到 `./metadata` 目录 + - 自定义输出目录:支持指定自定义输出目录 + - 格式化输出:支持格式化 YAML 输出 + - 可复用函数:导出了可复用的函数,便于其他模块调用 -## 功能特性 +3. **使用工具** + - 基本用法:`node trae/skills/convert-plugin-to-yaml.js <插件文件路径>` + - 批量转换:`node trae/skills/convert-plugin-to-yaml.js <目录路径>` + - 自定义输出目录:`node trae/skills/convert-plugin-to-yaml.js <插件文件路径> --output <输出目录>` + - 格式化输出:`node trae/skills/convert-plugin-to-yaml.js <插件文件路径> --format` + - 示例: + - 转换 Access 插件:`node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js` + - 转换 Task 插件:`node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js` + - 转换 DNS Provider 插件:`node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/dns-provider.js` + - 批量转换插件:`node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/` + - 自定义输出目录:`node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js --output ./configs` -- **单个插件转换**:支持指定单个插件文件进行转换,而不是扫描整个目录 -- **自动类型识别**:自动识别插件类型(Access、Task、DNS Provider、Notification、Addon) -- **详细日志输出**:提供详细的转换过程日志,便于调试 -- **YAML 配置生成**:生成标准的 YAML 配置文件 -- **配置文件保存**:自动将生成的配置保存到 `./metadata` 目录 -- **可复用函数**:导出了可复用的函数,便于其他模块调用 +4. **理解转换过程** + - 加载插件模块:使用 `import()` 动态加载指定的插件文件 + - 分析插件定义:检查模块导出的对象,寻找带有 `define` 属性的插件 + - 识别插件类型:根据插件的继承关系或属性识别插件类型 + - 生成 YAML 配置:基于插件定义生成标准的 YAML 配置 + - 保存配置文件:将生成的配置保存到 `./metadata` 目录 -## 使用方法 +5. **了解输出说明** + - 命令行输出:插件加载状态、插件导出的对象列表、插件类型识别结果、生成的 YAML 配置内容、配置文件保存路径 + - 配置文件命名规则:`<插件类型>[_<子类型>]_<插件名称>.yaml` -### 基本用法 +6. **理解插件类型识别逻辑** + - DNS Provider:如果插件定义中包含 `accessType` 属性 + - Task:如果插件继承自 `AbstractTaskPlugin` + - Notification:如果插件继承自 `BaseNotification` + - Access:如果插件继承自 `BaseAccess` + - Addon:如果插件继承自 `BaseAddon` -```bash -node trae/skills/convert-plugin-to-yaml.js <插件文件路径> -``` +7. **遵循注意事项** + - 文件路径:插件文件路径可以是相对路径或绝对路径 + - 文件格式:仅支持 `.js` 文件,不支持 `.ts` 文件(需要先编译) + - 依赖安装:执行前确保已安装所有必要的依赖 + - 配置目录:如果 `./metadata` 目录不存在,工具会自动创建 + - 错误处理:如果插件加载失败或识别失败,工具会输出错误信息但不会终止执行 -### 示例 +## 输出规范 +- 必须包含工具的使用方法和示例 +- 必须包含转换过程的详细说明 +- 必须包含输出说明和配置文件命名规则 +- 必须包含插件类型识别逻辑 +- 必须包含注意事项和故障排除建议 + +## 示例 + +### 示例 1: 转换单个 Access 插件 + +#### 用户输入 +将 Access 插件转换为 YAML 配置文件。 + +#### 你的回答 ```bash # 转换 Access 插件 node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js - -# 转换 Task 插件 -node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js - -# 转换 DNS Provider 插件 -node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/dns-provider.js ``` -## 转换过程 - -1. **加载插件模块**:使用 `import()` 动态加载指定的插件文件 -2. **分析插件定义**:检查模块导出的对象,寻找带有 `define` 属性的插件 -3. **识别插件类型**:根据插件的继承关系或属性识别插件类型 -4. **生成 YAML 配置**:基于插件定义生成标准的 YAML 配置 -5. **保存配置文件**:将生成的配置保存到 `./metadata` 目录 - -## 输出说明 - -### 命令行输出 - -执行转换命令后,工具会输出以下信息: - -- 插件加载状态 -- 插件导出的对象列表 -- 插件类型识别结果 -- 生成的 YAML 配置内容 -- 配置文件保存路径 - -### 配置文件命名规则 - -生成的配置文件命名规则为: - -``` -<插件类型>[_<子类型>]_<插件名称>.yaml -``` - -例如: -- `access_demo.yaml`(Access 插件) -- `deploy_DemoTest.yaml`(Task 插件) -- `dnsProvider_demo.yaml`(DNS Provider 插件) - -## 插件类型识别逻辑 - -工具通过以下逻辑识别插件类型: - -1. **DNS Provider**:如果插件定义中包含 `accessType` 属性 -2. **Task**:如果插件继承自 `AbstractTaskPlugin` -3. **Notification**:如果插件继承自 `BaseNotification` -4. **Access**:如果插件继承自 `BaseAccess` -5. **Addon**:如果插件继承自 `BaseAddon` - -## 注意事项 - -1. **文件路径**:插件文件路径可以是相对路径或绝对路径 -2. **文件格式**:仅支持 `.js` 文件,不支持 `.ts` 文件(需要先编译) -3. **依赖安装**:执行前确保已安装所有必要的依赖 -4. **配置目录**:如果 `./metadata` 目录不存在,工具会自动创建 -5. **错误处理**:如果插件加载失败或识别失败,工具会输出错误信息但不会终止执行 - -## 代码结构 - -### 主要函数 - -1. **isPrototypeOf(value, cls)**:检查对象是否是指定类的原型 -2. **loadSingleModule(filePath)**:加载单个插件模块 -3. **convertSinglePlugin(pluginPath)**:分析单个插件并生成 YAML 配置 -4. **main()**:主函数,处理命令行参数并执行转换 - -### 导出函数 - -工具导出了以下函数,便于其他模块调用: - -```javascript -export { - convertSinglePlugin, // 转换单个插件 - loadSingleModule, // 加载单个模块 - isPrototypeOf // 检查原型关系 -}; -``` - -## 应用场景 - -1. **插件开发**:在开发新插件时,快速生成配置文件 -2. **插件调试**:查看插件的内部定义和配置 -3. **插件管理**:批量转换现有插件为标准配置格式 -4. **自动化构建**:集成到构建流程中,自动生成插件配置 - -## 示例输出 - -### 转换 Access 插件示例 - +#### 输出 ```bash $ node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js 开始转换插件: packages/ui/certd-server/src/plugins/plugin-demo/access.js @@ -142,30 +106,117 @@ YAML 配置已保存到: ./metadata/access_demo.yaml 插件转换完成! ``` -### 转换 Task 插件示例 +### 示例 2: 批量转换插件 + +#### 用户输入 +批量转换目录中的所有插件为 YAML 配置文件。 + +#### 你的回答 ```bash -$ node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js +# 批量转换插件 +node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/ +``` + +#### 输出 +```bash +$ node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/ +开始转换目录: packages/ui/certd-server/src/plugins/ + +正在处理文件: packages/ui/certd-server/src/plugins/plugin-demo/access.js +开始转换插件: packages/ui/certd-server/src/plugins/plugin-demo/access.js +插件模块导出了 1 个对象: DemoAccess +处理插件: DemoAccess +插件类型: access +脚本路径: packages/ui/certd-server/src/plugins/plugin-demo/access.js + +生成的 YAML 配置: +name: demo +title: 授权插件示例 +desc: 这是一个示例授权插件,用于演示如何实现一个授权插件 +icon: clarity:plugin-line +pluginType: access +type: builtIn +scriptFilePath: packages/ui/certd-server/src/plugins/plugin-demo/access.js + +YAML 配置已保存到: ./metadata/access_demo.yaml +插件转换完成! + +正在处理文件: packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js 开始转换插件: packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js 插件模块导出了 1 个对象: DemoTest 处理插件: DemoTest -插件类型: deploy +插件类型: task 脚本路径: packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js 生成的 YAML 配置: name: DemoTest title: Demo-测试插件 -desc: "" +desc: 这是一个示例任务插件,用于演示如何实现一个任务插件 icon: clarity:plugin-line +pluginType: task group: other -default: - strategy: - runStrategy: SkipWhenSucceed -pluginType: deploy type: builtIn scriptFilePath: packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js -YAML 配置已保存到: ./metadata/deploy_DemoTest.yaml +YAML 配置已保存到: ./metadata/task_DemoTest.yaml +插件转换完成! + +正在处理文件: packages/ui/certd-server/src/plugins/plugin-demo/dns-provider.js +开始转换插件: packages/ui/certd-server/src/plugins/plugin-demo/dns-provider.js +插件模块导出了 1 个对象: DemoDnsProvider +处理插件: DemoDnsProvider +插件类型: dns-provider +脚本路径: packages/ui/certd-server/src/plugins/plugin-demo/dns-provider.js + +生成的 YAML 配置: +name: demo +title: Dns提供商Demo +desc: dns provider示例 +icon: clarity:plugin-line +pluginType: dns-provider +accessType: demo +order: 99 +type: builtIn +scriptFilePath: packages/ui/certd-server/src/plugins/plugin-demo/dns-provider.js + +YAML 配置已保存到: ./metadata/dns-provider_demo.yaml +插件转换完成! + +批量转换完成,共处理 3 个插件文件 +``` + +### 示例 3: 自定义输出目录 + +#### 用户输入 +将插件转换为 YAML 配置文件,并保存到自定义目录。 + +#### 你的回答 + +```bash +# 自定义输出目录 +node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js --output ./configs +``` + +#### 输出 +```bash +$ node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js --output ./configs +开始转换插件: packages/ui/certd-server/src/plugins/plugin-demo/access.js +插件模块导出了 1 个对象: DemoAccess +处理插件: DemoAccess +插件类型: access +脚本路径: packages/ui/certd-server/src/plugins/plugin-demo/access.js + +生成的 YAML 配置: +name: demo +title: 授权插件示例 +desc: 这是一个示例授权插件,用于演示如何实现一个授权插件 +icon: clarity:plugin-line +pluginType: access +type: builtIn +scriptFilePath: packages/ui/certd-server/src/plugins/plugin-demo/access.js + +YAML 配置已保存到: ./configs/access_demo.yaml 插件转换完成! ``` @@ -196,6 +247,30 @@ YAML 配置已保存到: ./metadata/deploy_DemoTest.yaml - **尝试简化插件**:如果转换失败,尝试创建一个最小化的插件示例进行测试 - **检查依赖版本**:确保使用的依赖版本与 Certd 兼容 -## 总结 +## 代码结构 -插件转换工具是一个方便实用的工具,它可以帮助开发者快速生成插件的 YAML 配置文件,简化插件的注册和管理过程。通过命令行参数指定单个插件文件,工具会自动完成类型识别、配置生成和保存等操作,大大提高了插件开发和管理的效率。 \ No newline at end of file +### 主要函数 + +1. **isPrototypeOf(value, cls)**:检查对象是否是指定类的原型 +2. **loadSingleModule(filePath)**:加载单个插件模块 +3. **convertSinglePlugin(pluginPath)**:分析单个插件并生成 YAML 配置 +4. **main()**:主函数,处理命令行参数并执行转换 + +### 导出函数 + +工具导出了以下函数,便于其他模块调用: + +```javascript +export { + convertSinglePlugin, // 转换单个插件 + loadSingleModule, // 加载单个模块 + isPrototypeOf // 检查原型关系 +}; +``` + +## 应用场景 + +1. **插件开发**:在开发新插件时,快速生成配置文件 +2. **插件调试**:查看插件的内部定义和配置 +3. **插件管理**:批量转换现有插件为标准配置格式 +4. **自动化构建**:集成到构建流程中,自动生成插件配置 \ No newline at end of file diff --git a/.trae/skills/task-plugin-dev/SKILL.md b/.trae/skills/task-plugin-dev/SKILL.md index fd1b5efd8..0d71fb7d5 100644 --- a/.trae/skills/task-plugin-dev/SKILL.md +++ b/.trae/skills/task-plugin-dev/SKILL.md @@ -1,12 +1,73 @@ +--- +name: task-plugin-dev +description: 用于开发 Certd 系统中的 Task 插件,继承自 AbstractTaskPlugin 类,被流水线调用 execute 方法将证书部署到对应的应用上。当用户需要创建任务插件、部署证书、自动化任务或修改现有 Task 插件时触发。 +version: 1.0.0 +--- + # Task 插件开发技能 -## 什么是 Task 插件 +## 角色定义 +你是一名 Certd 插件开发专家,擅长创建和实现 Task 类型的插件,熟悉 TypeScript 编程和 Certd 插件开发规范。 -Task 插件是 Certd 系统中的部署任务插件,它继承自 `AbstractTaskPlugin` 类,被流水线调用 `execute` 方法,将证书部署到对应的应用上。 +## 核心指令 +请严格按照以下步骤执行任务: -## 开发步骤 +1. **导入必要的依赖** + - 导入 `AbstractTaskPlugin`, `IsTaskPlugin`, `PageSearch`, `pluginGroups`, `RunStrategy`, `TaskInput` 等必要的类型和装饰器 + - 导入 `CertInfo`, `CertReader` 等证书相关类型 + - 导入 `createCertDomainGetterInputDefine`, `createRemoteSelectInputDefine` 等工具函数 + - 导入 `optionsUtils` 等辅助工具 + - 导入 `CertApplyPluginNames` 等常量 -### 1. 导入必要的依赖 +2. **使用 @IsTaskPlugin 注解注册插件** + - 配置插件的唯一标识、标题、图标 + - 设置插件分组 + - 配置默认策略(如 `SkipWhenSucceed`) + - 确保类名与插件名称一致 + +3. **定义任务输入参数** + - 使用 `@TaskInput` 注解定义各种输入参数 + - 必须包含证书选择参数,用于获取前置任务输出的域名证书 + - 可以添加授权选择框、文本输入、选择框等参数 + - 使用 `createCertDomainGetterInputDefine` 获取证书域名列表 + +4. **实现动态显隐配置** + - 使用 `mergeScript` 实现根据其他输入值动态控制输入项的显隐状态 + - 利用 `ctx.compute` 函数访问表单中的其他字段值 + +5. **实现插件方法** + - **onInstance 方法**:插件实例化时执行的初始化操作 + - **execute 方法**:插件的核心执行逻辑 + - 获取授权信息 + - 读取证书信息 + - 执行具体的部署逻辑 + - 处理错误并记录日志 + - 实现幂等性:确保重复执行不会导致问题 + - 实现超时处理:设置合理的超时时间 + - 实现回滚机制:在部署失败时能够回滚到之前的状态 + - **后端获取选项方法**:用于前端从后端获取选项的方法 + +6. **遵循开发最佳实践** + - 插件命名:遵循命名规范,大写字母开头,驼峰命名 + - 类名规范:类名应与插件名称一致 + - 日志输出:使用 `this.logger` 输出日志 + - 错误处理:捕获并记录执行过程中的错误 + - 授权获取:使用 `this.getAccess(accessId)` 获取授权信息 + +## 输出规范 +- 必须包含完整的插件实现代码 +- 代码必须包含详细的注释说明 +- 提供完整的示例代码,展示插件的使用方法 +- 包含开发注意事项和最佳实践 + +## 示例 + +### 示例 1: 基本 Task 插件 + +#### 用户输入 +创建一个 Task 插件,用于将证书部署到对应的应用上。 + +#### 你的回答 ```typescript import { AbstractTaskPlugin, IsTaskPlugin, PageSearch, pluginGroups, RunStrategy, TaskInput } from '@certd/pipeline'; @@ -14,247 +75,9 @@ import { CertInfo, CertReader } from '@certd/plugin-cert'; import { createCertDomainGetterInputDefine, createRemoteSelectInputDefine } from '@certd/plugin-lib'; import { optionsUtils } from '@certd/basic'; import { CertApplyPluginNames} from '@certd/plugin-cert'; -``` -### 2. 使用 @IsTaskPlugin 注解注册插件 - -```typescript @IsTaskPlugin({ - // 命名规范,插件类型+功能,大写字母开头,驼峰命名 - name: 'DemoTest', - title: 'Demo-测试插件', // 插件标题 - icon: 'clarity:plugin-line', // 插件图标 - // 插件分组 - group: pluginGroups.other.key, - default: { - // 默认值配置照抄即可 - strategy: { - runStrategy: RunStrategy.SkipWhenSucceed, - }, - }, -}) -// 类名规范,跟上面插件名称(name)一致 -export class DemoTest extends AbstractTaskPlugin { - // 插件实现... -} -``` - -### 3. 定义任务输入参数 - -使用 `@TaskInput` 注解定义任务输入参数: - -```typescript -// 测试参数 -@TaskInput({ - title: '属性示例', - value: '默认值', - component: { - // 前端组件配置,具体配置见组件文档 https://www.antdv.com/components/input-cn - name: 'a-input', - vModel: 'value', // 双向绑定组件的 props 名称 - }, - helper: '帮助说明,[链接](https://certd.docmirror.cn)', - required: false, // 是否必填 -}) -text!: string; - -// 证书选择,此项必须要有 -@TaskInput({ - title: '域名证书', - helper: '请选择前置任务输出的域名证书', - component: { - name: 'output-selector', - from: [...CertApplyPluginNames], - }, - // required: true, // 必填 -}) -cert!: CertInfo; - -@TaskInput(createCertDomainGetterInputDefine({ props: { required: false } })) -// 前端可以展示,当前申请的证书域名列表 -certDomains!: string[]; - -// 授权选择框 -@TaskInput({ - title: 'demo授权', - helper: 'demoAccess授权', - component: { - name: 'access-selector', - vModel:"modelValue", - type: "demo", // access类型,让用户固定选择这种类型的access - }, - // rules: [{ required: true, message: '此项必填' }], - // required: true, // 必填 -}) -accessId!: string; -``` - -### 4. 动态显隐配置(mergeScript) - -使用 `mergeScript` 可以实现根据其他输入值动态控制当前输入项的显隐状态。 - -```typescript -@TaskInput({ - title: '匹配模式', - component: { - name: 'select', - options: [ - { label: '手动选择', value: 'manual' }, - { label: '根据证书匹配', value: 'auto' }, - ], - }, - default: 'manual', -}) -domainMatchMode!: 'manual' | 'auto'; - -@TaskInput( - createRemoteSelectInputDefine({ - title: 'DCDN加速域名', - helper: '你在阿里云上配置的DCDN加速域名', - action: DeployCertToAliyunDCDN.prototype.onGetDomainList.name, - watches: ['certDomains', 'accessId'], - required: true, - mergeScript: ` - return { - show: ctx.compute(({form})=>{ - return domainMatchMode === "manual" - }) - } - `, - }) -) -domainName!: string | string[]; -``` - -`mergeScript` 中的 `ctx.compute` 函数接收一个回调函数,通过 `form` 参数可以访问表单中的其他字段值。 - -### 5. 实现插件方法 - -#### 5.1 插件实例化时执行的方法 - -```typescript -// 插件实例化时执行的方法 -async onInstance() {} -``` - -#### 5.2 插件执行方法 - - 1. 开始写代码之前,需要先研究应用的部署接口逻辑, 一般有两种 - a 用户选择网站ID,给网站部署新证书 - b 用户选择证书ID,只需要更新证书即可 - 无论哪一种都要保证多次执行都能针对同一个对象部署证书,出错后重新运行能够回归到正常状态 - 反例: 比如根据证书id=1进行更新,结果证书部署完成之后,证书id变成了2,那么再次运行插件,插件的输出参数仍然是1,就无法达到持续更更新证书的目的。 - 这部分逻辑每一步都需要明确的接口文档支撑,不能依赖于经验 - - 2. 前置证书选择 - a. 前置证书可以选择原始的certInfo类型,也有可能是上传到平台之后返回的证书id,比如阿里的CAS证书id,部署时要区分这两者 - b. 如果接口需要上传后的证书id,那么部署时要先将证书上传,再部署 - c. 如果接口需要原始的certInfo类型,那么直接使用certInfo部署证书 - d. 当两者都支持时,判断用户选择的证书类型,再考虑优先上传再部署 - - 3. 证书清理 - a. 如果是先上传再部署的,那么在部署完成后,可能需要考虑清理证书 - - -```typescript -// 插件执行方法 -async execute(): Promise { - const { select, text, cert, accessId } = this; - - try { - const access = await this.getAccess(accessId); - this.logger.debug('access', access); - } catch (e) { - this.logger.error('获取授权失败', e); - } - - try { - const certReader = new CertReader(cert); - this.logger.debug('certReader', certReader); - } catch (e) { - this.logger.error('读取crt失败', e); - } - - this.logger.info('DemoTestPlugin execute'); - this.logger.info('text:', text); - this.logger.info('select:', select); - this.logger.info('switch:', this.switch); - this.logger.info('授权id:', accessId); - - // 具体的部署逻辑 - -} -``` - -#### 5.3 后端获取选项方法 - -使用 `createRemoteSelectInputDefine` 创建远程选择输入项,`action` 指向的方法接收 `PageSearch` 参数并返回 `{ list, total }` 格式。 - -```typescript -@TaskInput( - createRemoteSelectInputDefine({ - title: '从后端获取选项', - helper: '选择时可以从后端获取选项', - action: DemoTest.prototype.onGetSiteList.name, - // 当以下参数变化时,触发获取选项 - watches: ['certDomains', 'accessId'], - required: true, - }) -) -siteName!: string | string[]; - -// 从后端获取选项的方法,接收PageSearch参数 -async onGetSiteList(data: PageSearch) { - if (!this.accessId) { - throw new Error('请选择Access授权'); - } - - // @ts-ignore - const access = await this.getAccess(this.accessId); - - // const siteRes = await access.GetDomainList(data); - // 以下是模拟数据 - const siteRes = [ - { id: 1, siteName: 'site1.com' }, - { id: 2, siteName: 'site2.com' }, - { id: 3, siteName: 'site2.com' }, - ]; - // 转换为前端所需要的格式 - const options = siteRes.map((item: any) => { - return { - value: item.siteName, - label: item.siteName, - domain: item.siteName, - }; - }); - - // 返回{list, total}格式 - return { - list: optionsUtils.buildGroupOptions(options, this.certDomains), - total: siteRes.length, - }; -} -``` - -## 注意事项 - -1. **插件命名**:插件名称应遵循命名规范,大写字母开头,驼峰命名。 -2. **类名规范**:类名应与插件名称(name)一致。 -3. **证书选择**:必须包含证书选择参数,用于获取前置任务输出的域名证书。 -4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`。 -5. **错误处理**:执行过程中的错误应被捕获并记录。 -6. **授权获取**:使用 `this.getAccess(accessId)` 获取授权信息。 - -## 完整示例 - -```typescript -import { AbstractTaskPlugin, IsTaskPlugin, PageSearch, pluginGroups, RunStrategy, TaskInput } from '@certd/pipeline'; -import { CertInfo, CertReader } from '@certd/plugin-cert'; -import { createCertDomainGetterInputDefine, createRemoteSelectInputDefine } from '@certd/plugin-lib'; -import { optionsUtils } from '@certd/basic'; -import { CertApplyPluginNames} from '@certd/plugin-cert'; -@IsTaskPlugin({ - //命名规范,插件类型+功能(就是目录plugin-demo中的demo),大写字母开头,驼峰命名 + //命名规范,插件类型+功能,大写字母开头,驼峰命名 name: 'DemoTest', title: 'Demo-测试插件', icon: 'clarity:plugin-line', @@ -303,7 +126,7 @@ export class DemoTest extends AbstractTaskPlugin { title: '动态显隐', helper: '我会根据选择框的值进行显隐', show: true, //动态计算的值会覆盖它 - //动态计算脚本, mergeScript返回的对象会合并当前配置,此处演示 show的值会被动态计算结果覆盖,show的值根据用户选择的select的值决定 + //动态计算脚本, mergeScript返回的对象会合并当前配置 mergeScript: ` return { show: ctx.compute(({form})=>{ @@ -341,6 +164,7 @@ export class DemoTest extends AbstractTaskPlugin { }, }) switch!: boolean; + //证书选择,此项必须要有 @TaskInput({ title: '域名证书', @@ -409,6 +233,7 @@ export class DemoTest extends AbstractTaskPlugin { this.logger.info('switch:', this.switch); this.logger.info('授权id:', accessId); + // 具体的部署逻辑 // const res = await this.http.request({ // url: 'https://api.demo.com', // method: 'GET', @@ -451,4 +276,371 @@ export class DemoTest extends AbstractTaskPlugin { }; } } +``` + +### 示例 2: Nginx 部署 Task 插件 + +#### 用户输入 +创建一个 Task 插件,用于将证书部署到 Nginx 服务器上。 + +#### 你的回答 + +```typescript +import { AbstractTaskPlugin, CertInfo, IsTaskPlugin, TaskInput, pluginGroups, RunStrategy } from '@certd/pipeline'; +import { CertReader } from '@certd/plugin-lib'; + +/** + * Nginx 证书部署插件 + */ +@IsTaskPlugin({ + name: 'NginxDeploy', + title: 'Nginx 部署', + desc: '将证书部署到 Nginx 服务器上', + icon: 'clarity:server-line', + group: pluginGroups.deploy.key, + default: { + strategy: { + runStrategy: RunStrategy.SkipWhenSucceed, + }, + }, +}) +export class NginxDeploy extends AbstractTaskPlugin { + /** + * 服务器授权 + */ + @TaskInput({ + title: '服务器授权', + component: { + name: 'access-selector', + vModel: 'accessId', + accessTypes: ['ssh'], + placeholder: '请选择服务器授权', + }, + required: true, + }) + accessId = ''; + + /** + * 域名证书 + */ + @TaskInput({ + title: '域名证书', + component: { + name: 'output-selector', + from: ['CertApply', 'CertApplyCloudflare'], + field: 'cert', + }, + required: true, + }) + cert!: CertInfo; + + /** + * 证书路径 + */ + @TaskInput({ + title: '证书路径', + value: '/etc/nginx/ssl', + component: { + name: 'a-input', + placeholder: '请输入证书存储路径', + }, + required: true, + }) + certPath = ''; + + /** + * Nginx 配置文件路径 + */ + @TaskInput({ + title: 'Nginx 配置文件', + value: '/etc/nginx/conf.d', + component: { + name: 'a-input', + placeholder: '请输入 Nginx 配置文件路径', + }, + required: true, + }) + nginxConfPath = ''; + + /** + * 服务名称 + */ + @TaskInput({ + title: '服务名称', + component: { + name: 'a-input', + placeholder: '请输入服务名称(用于生成配置文件)', + }, + required: true, + }) + serviceName = ''; + + /** + * 执行部署 + */ + async execute(): Promise { + this.logger.info('开始部署证书到 Nginx'); + + try { + // 1. 获取服务器授权 + const sshAccess = await this.getAccess(this.accessId); + this.logger.info('获取服务器授权成功'); + + // 2. 读取证书信息 + const certReader = new CertReader(this.cert); + const cert = certReader.getCert(); + const key = certReader.getKey(); + const fullchain = certReader.getFullChain(); + this.logger.info('读取证书信息成功'); + + // 3. 准备部署路径 + const certFile = `${this.certPath}/${this.serviceName}.pem`; + const keyFile = `${this.certPath}/${this.serviceName}.key`; + const confFile = `${this.nginxConfPath}/${this.serviceName}.conf`; + + // 4. 创建证书目录 + await sshAccess.exec(`mkdir -p ${this.certPath}`); + this.logger.info('创建证书目录成功'); + + // 5. 上传证书文件 + await sshAccess.uploadContent(cert, certFile); + await sshAccess.uploadContent(key, keyFile); + await sshAccess.uploadContent(fullchain, `${this.certPath}/${this.serviceName}-fullchain.pem`); + this.logger.info('上传证书文件成功'); + + // 6. 生成 Nginx 配置 + const nginxConf = `server { + listen 443 ssl; + server_name ${this.cert.domains.join(' ')}; + + ssl_certificate ${certFile}; + ssl_certificate_key ${keyFile}; + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384; + ssl_prefer_server_ciphers on; + + location / { + proxy_pass http://localhost:80; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } +} +`; + + // 7. 上传 Nginx 配置 + await sshAccess.uploadContent(nginxConf, confFile); + this.logger.info('上传 Nginx 配置成功'); + + // 8. 测试 Nginx 配置 + const testResult = await sshAccess.exec('nginx -t'); + if (testResult.includes('test is successful')) { + this.logger.info('Nginx 配置测试成功'); + } else { + throw new Error(`Nginx 配置测试失败: ${testResult}`); + } + + // 9. 重启 Nginx 服务 + await sshAccess.exec('systemctl reload nginx'); + this.logger.info('重启 Nginx 服务成功'); + + this.logger.info('证书部署到 Nginx 成功'); + } catch (error) { + this.logger.error('部署失败:', error); + throw new Error(`部署到 Nginx 失败: ${error.message}`); + } + } +} + +// 实例化插件 +new NginxDeploy(); +``` + +### 示例 3: 阿里云 OSS 部署 Task 插件 + +#### 用户输入 +创建一个 Task 插件,用于将证书部署到阿里云 OSS 上。 + +#### 你的回答 + +```typescript +import { AbstractTaskPlugin, CertInfo, IsTaskPlugin, TaskInput, pluginGroups, RunStrategy } from '@certd/pipeline'; +import { CertReader } from '@certd/plugin-lib'; + +/** + * 阿里云 OSS 证书部署插件 + */ +@IsTaskPlugin({ + name: 'AliyunOSSDeploy', + title: '阿里云 OSS 部署', + desc: '将证书部署到阿里云 OSS 存储上', + icon: 'clarity:cloud-line', + group: pluginGroups.deploy.key, + default: { + strategy: { + runStrategy: RunStrategy.SkipWhenSucceed, + }, + }, +}) +export class AliyunOSSDeploy extends AbstractTaskPlugin { + /** + * 阿里云授权 + */ + @TaskInput({ + title: '阿里云授权', + component: { + name: 'access-selector', + vModel: 'accessId', + accessTypes: ['aliyun'], + placeholder: '请选择阿里云授权', + }, + required: true, + }) + accessId = ''; + + /** + * 域名证书 + */ + @TaskInput({ + title: '域名证书', + component: { + name: 'output-selector', + from: ['CertApply', 'CertApplyCloudflare'], + field: 'cert', + }, + required: true, + }) + cert!: CertInfo; + + /** + * OSS 存储桶 + */ + @TaskInput({ + title: 'OSS 存储桶', + component: { + name: 'a-input', + placeholder: '请输入 OSS 存储桶名称', + }, + required: true, + }) + bucketName = ''; + + /** + * 存储路径 + */ + @TaskInput({ + title: '存储路径', + value: 'ssl/', + component: { + name: 'a-input', + placeholder: '请输入证书存储路径', + }, + }) + storagePath = ''; + + /** + * 执行部署 + */ + async execute(): Promise { + this.logger.info('开始部署证书到阿里云 OSS'); + + try { + // 1. 获取阿里云授权 + const aliyunAccess = await this.getAccess(this.accessId); + this.logger.info('获取阿里云授权成功'); + + // 2. 读取证书信息 + const certReader = new CertReader(this.cert); + const cert = certReader.getCert(); + const key = certReader.getKey(); + const fullchain = certReader.getFullChain(); + this.logger.info('读取证书信息成功'); + + // 3. 准备存储路径 + const basePath = this.storagePath.endsWith('/') ? this.storagePath : `${this.storagePath}/`; + const certFileName = `${basePath}${this.cert.domains[0]}.pem`; + const keyFileName = `${basePath}${this.cert.domains[0]}.key`; + const fullchainFileName = `${basePath}${this.cert.domains[0]}-fullchain.pem`; + + // 4. 上传证书到 OSS + await aliyunAccess.uploadToOSS({ + bucket: this.bucketName, + key: certFileName, + content: cert, + }); + this.logger.info('上传证书文件成功'); + + await aliyunAccess.uploadToOSS({ + bucket: this.bucketName, + key: keyFileName, + content: key, + }); + this.logger.info('上传私钥文件成功'); + + await aliyunAccess.uploadToOSS({ + bucket: this.bucketName, + key: fullchainFileName, + content: fullchain, + }); + this.logger.info('上传完整证书链成功'); + + // 5. 设置文件访问权限(可选) + await aliyunAccess.setOSSObjectAcl({ + bucket: this.bucketName, + key: certFileName, + acl: 'private', + }); + + await aliyunAccess.setOSSObjectAcl({ + bucket: this.bucketName, + key: keyFileName, + acl: 'private', + }); + + await aliyunAccess.setOSSObjectAcl({ + bucket: this.bucketName, + key: fullchainFileName, + acl: 'private', + }); + this.logger.info('设置文件访问权限成功'); + + this.logger.info('证书部署到阿里云 OSS 成功'); + } catch (error) { + this.logger.error('部署失败:', error); + throw new Error(`部署到阿里云 OSS 失败: ${error.message}`); + } + } +} + +// 实例化插件 +new AliyunOSSDeploy(); +``` + +## 注意事项 + +1. **插件命名**:插件名称应遵循命名规范,大写字母开头,驼峰命名。 +2. **类名规范**:类名应与插件名称(name)一致。 +3. **证书选择**:必须包含证书选择参数,用于获取前置任务输出的域名证书。 +4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`,参数文本化,不要传对象,否则会输出`[object Object]}`。 +5. **错误处理**:执行过程中的错误应被捕获并记录。 +6. **授权获取**:使用 `this.getAccess(accessId)` 获取授权信息。 + +## 部署逻辑注意事项 + +1. **部署接口逻辑**: + - 研究应用的部署接口逻辑,一般有两种: + a. 用户选择网站ID,给网站部署新证书 + b. 用户选择证书ID,只需要更新证书即可 + - 保证多次执行都能针对同一个对象部署证书 + - 确保出错后重新运行能够回归到正常状态 + +2. **前置证书选择**: + - 前置证书可以是原始的 `certInfo` 类型,也可能是上传到平台之后返回的证书id + - 根据接口要求选择合适的证书类型: + a. 如果接口需要上传后的证书id,那么部署时要先将证书上传,再部署 + b. 如果接口需要原始的 `certInfo` 类型,那么直接使用 `certInfo` 部署证书 + c. 当两者都支持时,判断用户选择的证书类型,再考虑优先上传再部署 + +3. **证书清理**: + - 如果是先上传再部署的,那么在部署完成后,可能需要考虑清理证书 ``` \ No newline at end of file