@geek-fun/serverlessinsight 0.9.3 → 0.9.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/AGENTS.md +5 -2
  2. package/CHANGELOG.md +56 -0
  3. package/README.md +266 -179
  4. package/README.zh-CN.md +264 -147
  5. package/codecov +0 -0
  6. package/codecov.SHA256SUM +1 -1
  7. package/codecov.SHA256SUM.sig +13 -13
  8. package/dist/package.json +22 -19
  9. package/dist/src/commands/deploy.js +7 -2
  10. package/dist/src/commands/destroy.js +6 -3
  11. package/dist/src/commands/forceUnlock.js +16 -21
  12. package/dist/src/commands/index.js +26 -63
  13. package/dist/src/commands/migrate.js +105 -132
  14. package/dist/src/commands/plan.js +27 -3
  15. package/dist/src/commands/show.js +17 -6
  16. package/dist/src/common/aggregateState.js +185 -0
  17. package/dist/src/common/aggregateStore.js +247 -0
  18. package/dist/src/common/aliyunClient/apigwOperations.js +32 -9
  19. package/dist/src/common/apiClient.js +35 -12
  20. package/dist/src/common/constants.js +2 -1
  21. package/dist/src/common/context.js +22 -15
  22. package/dist/src/common/effectiveConfig.js +48 -0
  23. package/dist/src/common/index.js +5 -0
  24. package/dist/src/common/jsonOutput.js +2 -13
  25. package/dist/src/common/migrationMarker.js +0 -7
  26. package/dist/src/common/nameBuilder.js +2 -3
  27. package/dist/src/common/regionalMigration.js +261 -0
  28. package/dist/src/common/saasProtocol.js +41 -0
  29. package/dist/src/common/stateBackend/cosStateBackend.js +88 -8
  30. package/dist/src/common/stateBackend/index.js +42 -18
  31. package/dist/src/common/stateBackend/localStateBackend.js +61 -26
  32. package/dist/src/common/stateBackend/ossStateBackend.js +62 -9
  33. package/dist/src/common/stateBackend/remoteStateBackend.js +94 -94
  34. package/dist/src/common/stateBackend/saasStateBackend.js +327 -92
  35. package/dist/src/common/stateBackend/types.js +9 -0
  36. package/dist/src/common/stateManager.js +38 -11
  37. package/dist/src/common/stateScope.js +34 -0
  38. package/dist/src/common/stateStorageIO.js +31 -0
  39. package/dist/src/lang/en.js +48 -6
  40. package/dist/src/lang/index.js +28 -14
  41. package/dist/src/lang/zh-CN.js +48 -6
  42. package/dist/src/parser/index.js +25 -4
  43. package/dist/src/stack/aliyunStack/apigwDomainPlan.js +82 -0
  44. package/dist/src/stack/aliyunStack/apigwExecutor.js +4 -1
  45. package/dist/src/stack/aliyunStack/apigwPlanner.js +115 -55
  46. package/dist/src/stack/aliyunStack/apigwResource.js +169 -124
  47. package/dist/src/stack/aliyunStack/deployer.js +5 -5
  48. package/dist/src/stack/aliyunStack/destroyer.js +5 -5
  49. package/dist/src/stack/aliyunStack/fc3Planner.js +1 -1
  50. package/dist/src/stack/aliyunStack/fc3Resource.js +2 -2
  51. package/dist/src/stack/aliyunStack/planner.js +1 -1
  52. package/dist/src/stack/aliyunStack/sharedLogProject.js +2 -2
  53. package/dist/src/stack/ownershipTag.js +34 -26
  54. package/dist/src/stack/scfStack/deployer.js +5 -5
  55. package/dist/src/stack/scfStack/destroyer.js +5 -6
  56. package/dist/src/stack/scfStack/planner.js +1 -1
  57. package/dist/src/stack/scfStack/scfResource.js +1 -1
  58. package/dist/src/stack/scfStack/sharedLogset.js +5 -2
  59. package/dist/src/stack/volcengineStack/deployer.js +3 -3
  60. package/dist/src/stack/volcengineStack/destroyer.js +2 -3
  61. package/dist/src/stack/volcengineStack/planner.js +1 -1
  62. package/dist/src/stack/volcengineStack/sharedLogProject.js +4 -4
  63. package/dist/src/stack/volcengineStack/vefaasResource.js +1 -1
  64. package/dist/src/types/domains/state.js +28 -2
  65. package/dist/src/validator/rootSchema.js +8 -0
  66. package/dist/tsconfig.tsbuildinfo +1 -1
  67. package/package.json +22 -19
  68. package/release-notes.md +27 -56
  69. package/samples/README_TENCENT_COS.md +68 -26
  70. package/samples/README_TENCENT_SCF.md +47 -29
  71. package/.serverlessinsight/state-cdn-flow-app-cdn-flow-service.json.backup +0 -14
  72. package/.serverlessinsight/state-iam-test-app-iam-test-service.json.backup +0 -32
  73. package/.serverlessinsight/state-insight-poc-app-insight-poc-tencent.json.backup +0 -90
  74. package/.serverlessinsight/state-insight-poc-app-log-insight-poc-tencent-log.json.backup +0 -118
  75. package/.serverlessinsight/state-insight-poc-deploy-app-insight-poc-deploy.json.backup +0 -215
  76. package/.serverlessinsight/state-insight-poc-destroy-app-insight-poc-destroy.json.backup +0 -14
  77. package/.serverlessinsight/state-insight-poc-timer-app-insight-poc-timer.json.backup +0 -132
  78. package/.serverlessinsight/state-insight-volc-app-insight-volc.json.backup +0 -55
  79. package/.serverlessinsight/state-insight-volc-destroy-app-insight-volc-destroy.json.backup +0 -1
  80. package/.serverlessinsight/state-insight-volc-nested-app-insight-volc-nested.json.backup +0 -93
  81. package/.serverlessinsight/state-nested-drift-app-nested-drift-service.json.backup +0 -163
  82. package/.serverlessinsight/state-role-reconcile-test-app-role-reconcile-test-service.json.backup +0 -148
package/README.zh-CN.md CHANGED
@@ -4,28 +4,30 @@
4
4
 
5
5
  # ServerlessInsight
6
6
 
7
- **全生命周期跨云服务商的 Serverless 管理 —— 描述你的应用,其余交给我们。**
7
+ **面向阿里云、腾讯云与火山引擎的全生命周期 Serverless IaC 工具。**
8
8
 
9
- **开源。多云。基础设施即代码。**
10
-
11
- **面向阿里云 · 腾讯云 · 华为云 · 火山引擎的 Serverless 命令行工具。**
9
+ 用一份 YAML 定义函数、API 网关、存储与数据库——先预览计划,再放心部署,并持续运维。
12
10
 
13
11
  [![Release](https://img.shields.io/github/v/release/geek-fun/serverlessinsight?color=orange&label=release&logo=github)](https://github.com/geek-fun/serverlessinsight/releases)
14
12
  [![npm version](https://img.shields.io/npm/v/@geek-fun/serverlessinsight?color=orange&logo=npm)](https://www.npmjs.com/package/@geek-fun/serverlessinsight)
15
- [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg&logo=apache)](LICENSE)
16
- [![Stars](https://img.shields.io/github/stars/geek-fun/serverlessinsight&logo=github)](https://github.com/geek-fun/serverlessinsight/stargazers)
13
+ [![npm downloads](https://img.shields.io/npm/dm/@geek-fun/serverlessinsight?color=orange&logo=npm)](https://www.npmjs.com/package/@geek-fun/serverlessinsight)
14
+ [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?logo=apache)](LICENSE)
17
15
  [![CI](https://github.com/geek-fun/serverlessinsight/actions/workflows/node.yml/badge.svg)](https://github.com/geek-fun/serverlessinsight/actions/workflows/node.yml)
16
+ [![Stars](https://img.shields.io/github/stars/geek-fun/serverlessinsight?logo=github)](https://github.com/geek-fun/serverlessinsight/stargazers)
17
+ [![Issues](https://img.shields.io/github/issues/geek-fun/serverlessinsight?logo=github)](https://github.com/geek-fun/serverlessinsight/issues)
18
+
19
+ <p>
20
+ <img src="https://img.shields.io/badge/Node.js-%3E%3D22.12-339933?logo=nodedotjs&logoColor=white" alt="Node.js >= 22.12" />
21
+ <img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
22
+ </p>
18
23
 
19
24
  <p>
20
- <img src="https://img.shields.io/badge/Node.js-339933&logo=nodedotjs&logoColor=white"/>
21
- <img src="https://img.shields.io/badge/TypeScript-3178C6&logo=typescript&logoColor=white"/>
22
- <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00&logo=alibabacloud&logoColor=white"/>
23
- <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED&logo=tencentqq&logoColor=white"/>
24
- <img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white"/>
25
- <img src="https://img.shields.io/badge/AWS-232F3E&logo=amazonwebservices&logoColor=white"/>
25
+ <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00?logo=alibabacloud&logoColor=white" alt="阿里云" />
26
+ <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED?logo=tencentqq&logoColor=white" alt="腾讯云" />
27
+ <img src="https://img.shields.io/badge/Volcengine-1677FF?logoColor=white" alt="火山引擎" />
26
28
  </p>
27
29
 
28
- [npm](https://www.npmjs.com/package/@geek-fun/serverlessinsight) · [文档](https://serverlessinsight.geekfun.club) · [官网](https://serverlessinsight.geekfun.club) · [GitHub](https://github.com/geek-fun/serverlessinsight)
30
+ [npm](https://www.npmjs.com/package/@geek-fun/serverlessinsight) · [文档](https://serverlessinsight.com/docs.html) · [官网](https://serverlessinsight.com) · [示例](samples) · [更新日志](CHANGELOG.md) · [Issues](https://github.com/geek-fun/serverlessinsight/issues)
29
31
 
30
32
  简体中文 · [English](README.md)
31
33
 
@@ -33,123 +35,193 @@
33
35
 
34
36
  ---
35
37
 
36
- ServerlessInsight 是一个**跨云服务商的 Serverless 框架**——它用统一的单一工具替代各家云厂商专属的 CLI、Web 控制台和 DIY 脚本。用 YAML 定义一次你的 Serverless 基础设施,即可部署到阿里云、腾讯云、华为云等。可将其视为面向 Serverless 的 Terraform,专为函数、API 网关、存储和数据库而打造。
38
+ ServerlessInsight(`si`)是一个开源的跨云 Serverless 框架。你不再需要分别应付各家云厂商的 CLI、控制台点击和一次性脚本——只需在单一 YAML 文件中描述整套 Serverless 技术栈(函数、HTTP 入口、对象存储、数据库与数据表),剩下的计划、部署与运维交给 `si`。
37
39
 
38
- <p align="center">
39
- <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00?logo=alibabacloud&logoColor=white" />
40
- <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED?logo=tencentqq&logoColor=white" />
41
- <img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white" />
42
- <img src="https://img.shields.io/badge/Volcengine-1677FF?logoColor=white" />
43
- <img src="https://img.shields.io/badge/AWS-232F3E?logo=amazonwebservices&logoColor=white" />
44
- <img src="https://img.shields.io/badge/Azure-0078D4?logo=microsoftazure&logoColor=white" />
45
- <img src="https://img.shields.io/badge/GCP-4285F4?logo=googlecloud&logoColor=white" />
46
- </p>
40
+ 可以把它理解为面向 Serverless 的 Terraform:同一套声明式工作流,带状态追踪与漂移检测,专为函数、API 网关和 Serverless 数据服务而设计。无供应商锁定,Apache-2.0 许可。
47
41
 
48
- ## 安装
42
+ **当前可部署:** 阿里云、腾讯云、火山引擎。华为云、AWS、Azure 与 Google Cloud 见[路线图](#路线图)。
43
+
44
+ ## 目录
45
+
46
+ - [快速开始](#快速开始)
47
+ - [为什么选择 ServerlessInsight](#为什么选择-serverlessinsight)
48
+ - [功能特性](#功能特性)
49
+ - [支持的云服务商](#支持的云服务商)
50
+ - [文档](#文档)
51
+ - [路线图](#路线图)
52
+ - [架构](#架构)
53
+ - [开发](#开发)
54
+ - [社区](#社区)
55
+ - [贡献](#贡献)
56
+ - [赞助](#赞助)
57
+ - [许可证](#许可证)
58
+
59
+ ## 快速开始
60
+
61
+ **需要 Node.js 22.12 或更高版本。**
49
62
 
50
63
  ```bash
51
64
  npm install -g @geek-fun/serverlessinsight
52
65
  si --version
53
66
  ```
54
67
 
55
- ## 核心特性
68
+ 创建 `serverlessinsight.yml`:
56
69
 
57
- ### 多云支持,统一配置
70
+ ```yaml
71
+ version: 0.0.1
72
+
73
+ provider:
74
+ name: aliyun
75
+ region: cn-hongkong
76
+
77
+ app: hello-world
78
+ service: hello-world-api
79
+
80
+ functions:
81
+ hello_function:
82
+ name: hello-world-fn
83
+ code:
84
+ runtime: nodejs18
85
+ handler: index.handler
86
+ path: ./src
87
+ memory: 512
88
+ timeout: 10
58
89
 
59
- 使用 YAML 一次性定义你的基础设施,即可部署到阿里云、腾讯云、华为云和火山引擎——AWS、Azure 和 GCP 已在路线图中。不再需要为每个云厂商疲于应付专属 CLI 或 Terraform 模块。
90
+ events:
91
+ api_gateway:
92
+ type: API_GATEWAY
93
+ name: my-api-gateway
94
+ triggers:
95
+ - method: GET
96
+ path: /api/hello
97
+ backend: ${functions.hello_function}
98
+ ```
60
99
 
61
- - **统一配置** —— 所有云服务商共用单一 `serverless.yml` 格式
62
- - **云厂商专属模板生成** —— 根据配置生成原生 IaC 模板
63
- - **跨云感知** —— 同一套抽象可在不同云之间通用
100
+ 然后:
64
101
 
65
- | 云服务商 | 函数 | API 网关 | 存储 | 数据库 | 状态 |
66
- | ---------------- | ---------------- | ----------- | ----------- | ---------------- | ------ |
67
- | **阿里云** | ✅ FC3 | ✅ API 网关 | ✅ OSS | ✅ RDS, OTS, ESS | 稳定 |
68
- | **腾讯云** | ✅ SCF | 🚧 即将推出 | ✅ COS | ✅ TDSQL-C | 稳定 |
69
- | **火山引擎** | ✅ veFaaS | ✅ API 网关 | ✅ TOS | — | 稳定 |
70
- | **华为云** | 🚧 即将推出 | 🚧 即将推出 | 🚧 即将推出 | 🚧 即将推出 | 计划中 |
71
- | **AWS** | 🔜 计划中 | 🔜 计划中 | 🔜 计划中 | 🔜 计划中 | 计划中 |
72
- | **Azure** | 🔜 计划中 | 🔜 计划中 | 🔜 计划中 | 🔜 计划中 | 计划中 |
73
- | **Google Cloud** | 🔜 计划中 | 🔜 计划中 | 🔜 计划中 | 🔜 计划中 | 计划中 |
102
+ ```bash
103
+ si validate # 按 IaC Schema 校验配置
104
+ si diff # 展示将要发生的变更,不写入状态
105
+ si deploy --stage prod # 展示计划,确认后执行
106
+ si local # 在 http://localhost:4567 本地运行
107
+ si destroy --stage prod # 删除 si 创建的全部资源
108
+ ```
74
109
 
75
- ### 基础设施即代码
110
+ `si` discovers `serverlessinsight.yml` in the current directory; use `-f <path>` for another file. Select another provider with `-v tencent` or `-v volcengine`, a valid region and a compatible resource configuration. The override selects an independent deployment; adapt unsupported runtimes/resources first.
76
111
 
77
- 声明式 YAML 配置,内置校验、计划与状态管理——遵循成熟的 IaC 实践。
112
+ ## 为什么选择 ServerlessInsight
78
113
 
79
- - **部署前预览** —— `si plan` 在实际变更前精确展示将要发生的改动
80
- - **状态追踪** —— 基于本地状态文件的增量部署与漂移检测
81
- - **配置校验** —— 类型安全的模板校验在配置触达云端前捕获错误
82
- - **部分失败恢复** —— 即使部分资源失败,已成功部署的资源仍会被保存;重试即可继续
114
+ - **Serverless 原生,而非通用 IaC。** 函数、触发器、API 网关、域名、存储桶、数据库与数据表都是一等资源,并带有云厂商感知的默认值——无需手写 Terraform 模块或 SDK 封装脚本。
115
+ - **One configuration format across clouds.** Reuse supported primitives and variables; validate each target configuration before deployment.
116
+ - **变更之前先看计划。** `si diff` 只读取状态与线上资源、不写入任何内容;`si deploy` 执行的正是你确认过的那份计划,控制台里的手工改动会以漂移形式暴露。
117
+ - **为自动化而生。** 日志输出到 stderr,机器可读结果输出到 stdout,每个 JSON envelope 都带版本号,错误码跨语言环境保持稳定,退出码遵循 Terraform 惯例。
118
+ - **真正可用的本地开发。** 用同一份配置在本地运行处理函数、HTTP 路由、定时调度与存储桶端点——无需云账号或凭证。
119
+ - **开源、无锁定。** Apache-2.0 许可,状态可存放在本地文件或你自己的存储桶中,不引入任何专有运行时。
83
120
 
84
- ### 快速部署
121
+ ## 功能特性
85
122
 
86
- ```bash
87
- # 校验你的配置
88
- si validate -f serverless.yml
123
+ ### 多云支持,统一配置
124
+
125
+ Use one format across Alibaba Cloud, Tencent Cloud and Volcengine. Shared mappings handle supported differences; each target must support the declared runtimes and resources.
126
+
127
+ - **统一配置** —— 所有云厂商共用同一 `serverlessinsight.yml` 格式
128
+ - **厂商专属映射** —— 运行时名称、触发器结构与资源类型会翻译为对应云平台的原生值
129
+ - **Cross-provider validation** — unsupported target resources fail before cloud execution
89
130
 
90
- # 预览变更
91
- si plan -f serverless.yml
131
+ ### 部署前预览
92
132
 
93
- # 部署到生产环境
94
- si deploy -f serverless.yml -s prod
133
+ `si diff` 可预览阿里云、腾讯云与火山引擎上的全部变更。它会读取已配置的状态后端与线上云资源,但不应用变更、也不写入状态。
95
134
 
96
- # 完成后销毁
97
- si destroy -f serverless.yml
135
+ ```bash
136
+ si diff --stage dev
137
+ si diff --stage dev --json
138
+ si diff --stage dev --region cn-beijing -p memory=1024
139
+ si diff --stage dev --no-refresh
98
140
  ```
99
141
 
100
- ### 在 AI agent 与脚本中使用 si
142
+ 使用 `-p, --parameter <key=value>` 可重复覆盖配置变量。`--no-refresh` 会跳过已追踪资源的线上漂移检查,新资源的归属探测仍会执行。需提前配置好凭证与所选状态后端;读取失败会以错误退出。迁移自旧版本的状态会产生告警并保持原样。
143
+
144
+ 火山引擎的计划按依赖顺序包含函数、TOS 存储桶与 API Gateway 资源。
145
+
146
+ **退出码**:`si diff` 无变更时退出 `0`,有变更时退出 `2`(Terraform 惯例),出错时退出 `1`。`si validate` 校验通过退出 `0`,校验失败退出 `1`。
147
+
148
+ ### Independent provider and region deployments
149
+
150
+ Deployment identity is `Org / App / Service / Stage / Provider / Region`.
151
+ `app` and `service` stay literal in YAML; `-s`, `-v` and `-r` select one deployment.
152
+ A compatible YAML can be reused, or separate YAML files can describe different regional
153
+ resources. Selecting the same scope and backend location addresses the same deployment.
154
+ Changing provider/region creates or updates the selected deployment and preserves the
155
+ previous deployment until an explicitly scoped destroy. Provider-specific declarations
156
+ must be supported by the target cloud; overrides do not translate unsupported resources.
157
+
158
+ Local state stays at `.serverlessinsight/state-<app>-<service>.json`; Bucket Store keeps
159
+ the exact configured `key`. Both store a V4 aggregate partitioned by stage/provider/region
160
+ under one whole-file lock. Executors and SaaS snapshots use a single-deployment V4 view;
161
+ SaaS mutations require scope protocol 3. Cloud accounts remain credential context rather
162
+ than another identity dimension.
101
163
 
102
- CLI 专为 agent 与脚本驱动而设计:日志始终输出到 **stderr**,结果数据输出到
103
- **stdout**,因此将 stdout 管道给 `jq` 总能得到单个可解析的 JSON 文档。
164
+ See [deployment state and migration](docs/regional-deployment-state.md) for storage
165
+ credentials, automatic V3 upgrades, ownership handoff, lock behavior and recovery.
166
+
167
+ ### 基础设施即代码
168
+
169
+ 声明式 YAML 配置,内置校验、计划与状态管理,遵循成熟的 IaC 实践。
170
+
171
+ - **状态追踪** —— 基于 `.serverlessinsight/` 状态文件进行增量部署,支持本地、存储桶与 SaaS 后端
172
+ - **漂移检测** —— 在 `si` 之外被改动的资源会在下次部署前被标记出来
173
+ - **配置校验** —— 类型安全的模板校验在配置触达云端前捕获错误
174
+ - **部分失败恢复** —— 即使部分资源失败,已成功部署的资源仍会被保存;重试即可继续
175
+ - **状态锁** —— 阻止并发部署,必要时可用 `si force-unlock` 解锁
176
+
177
+ ### 为 AI Agent 与脚本而设计
178
+
179
+ CLI 专为 Agent 与 Shell 脚本驱动而设计:日志始终输出到 **stderr**,结果数据输出到 **stdout**,因此把 stdout 管道给 `jq` 总能得到单个可解析的 JSON 文档。
104
180
 
105
181
  ```bash
106
- si plan --json -f serverless.yml | jq '.summary'
107
- si validate --json -f serverless.yml | jq '.valid'
108
- si show --json -f serverless.yml | jq '.resourceCount'
109
- si schema | jq '.$id' # IaC 格式的自包含 draft-07 JSON Schema
182
+ si diff --json | jq '.summary'
183
+ si validate --json | jq '.valid'
184
+ si show --json | jq '.resourceCount'
185
+ si schema | jq '."$id"' # IaC 格式的自包含 draft-07 JSON Schema
110
186
  ```
111
187
 
112
- **稳定的输出 envelope**(每个都带版本号字段,结构只会在新版本号下变化):
113
-
114
- - `si plan --json` → `{ planVersion: 1, provider, app, service, stage,
115
- changes: [{ logicalId, type, action: "create|update|destroy|recreate",
116
- attributes, drifted?, driftReasons? }], summary: { create, update, destroy,
117
- recreate, unchanged } }`
118
- - `si validate --json` → `{ validateVersion: 1, valid, errors: [{ path,
119
- keyword, message, allowedValues? }] }`
120
- - `si show --json` → `{ showVersion: 1, provider, app, service, stage,
121
- stateLocation, backend: "saas|bucket_store|local", locked, lock, resources,
122
- resourceCount, ... }`
188
+ <details>
189
+ <summary><b>稳定的输出 envelope、错误码与颜色行为</b></summary>
190
+
191
+ 稳定的输出 envelope(每个都带版本号字段,结构只会在新版本号下变化):
192
+
193
+ - `si diff --json` → `{ planVersion: 2, provider, app, service, stage, region, changes: [{ logicalId, type, action: "create|update|destroy|recreate", attributes, drifted?, driftReasons? }], summary: { create, update, destroy, recreate, unchanged } }`
194
+ - `si validate --json` → `{ validateVersion: 1, valid, errors: [{ path, keyword, message, allowedValues? }] }`
195
+ - `si show --json` → `{ showVersion: 2, provider, app, service, stage, region, stateLocation, backend: "saas|bucket_store|local", locked, lock, resources, resourceCount, ... }`
123
196
  - 失败时(`--json` 模式)→ stdout 输出 `{ error: { code, message } }`
124
197
 
125
- **退出码**:`si plan` 无变更时退出 `0`,有变更时退出 `2`(terraform
126
- 惯例),出错时退出 `1`。`si validate` 校验通过退出 `0`,校验失败退出 `1`。
198
+ 稳定的错误码:错误 `code` 是翻译消息背后的 i18n key(例如 `RAM_ROLE_NOT_FOUND_IN_CLOUD`)——在所有语言环境下保持一致,Agent 可以据此映射自愈动作,不受 `LANG` 影响。
127
199
 
128
- **稳定错误码**:错误 `code` 是翻译消息背后的 i18n key(例如
129
- `RAM_ROLE_NOT_FOUND_IN_CLOUD`)——在所有语言环境下保持一致,agent
130
- 可以据此映射自愈动作,不受 `LANG` 影响。
200
+ 颜色:设置 `NO_COLOR` 环境变量([no-color.org](https://no-color.org))或传入 `--no-color` 时禁用 ANSI 颜色,保证非 TTY 环境下管道输出干净。
131
201
 
132
- **颜色**:设置 `NO_COLOR` 环境变量([no-color.org](https://no-color.org))或传入
133
- `--no-color` 时禁用 ANSI 颜色,保证非 TTY 环境下管道输出干净。
202
+ </details>
134
203
 
135
204
  ### 本地开发
136
205
 
137
- 无需部署到云端,即可本地运行和调试你的 Serverless 函数。
206
+ 无需部署到云端,也无需配置凭证,即可在本地运行和调试 Serverless 函数。
138
207
 
139
- - **LocalStack 服务** —— 在本地测试函数、存储桶和 API 端点
140
- - **定时触发器本地触发** —— 阿里云、腾讯云与火山引擎 `functions.*.triggers.timer` 调度按 UTC 墙钟执行(`@every` 自服务启动起算),以对应云平台的 timer 事件形状调用你的处理函数
141
- - **火山引擎 HTTP 调用** —— 为[文档化的本地子集](docs/local-development.md)提供 veFaaS Node.js 事件、context 与响应转换,附带[可运行示例](samples/volcengine-local/serverlessinsight.yml)
208
+ - **HTTP 函数** —— 为阿里云 FC、腾讯云 SCF 函数 URL 与火山引擎 veFaaS 提供原生的 event、context 与响应转换
209
+ - **定时触发器** —— `functions.*.triggers.timer` 调度按 UTC 墙钟执行,以对应云平台的 timer 事件形状调用你的处理函数
142
210
  - **存储桶文件服务** —— 通过 HTTP 访问本地存储文件,加速迭代
143
- - **同一配置,不同目标** —— `si local -f serverless.yml -s local` 复用你现有的配置
211
+ - **监听模式** —— 代码变更后自动重载
212
+ - **同一配置,不同目标** —— `si local -s dev` 复用你现有的配置
213
+
214
+ 支持范围与可运行示例详见[本地开发文档](docs/local-development.md):[腾讯云 SCF](samples/tencent-local/serverlessinsight.yml) 与[火山引擎 veFaaS](samples/volcengine-local/serverlessinsight.yml)。
144
215
 
145
216
  ### API 网关与自定义域名
146
217
 
147
218
  配置 HTTP 端点并绑定自定义域名,附带自动 DNS 验证。
148
219
 
149
- - **API 网关集成** —— 使用 HTTP 方法和路径定义触发器
150
- - **自定义域名绑定** —— 为 OSS 和 API 网关自动完成 CNAME + DNS TXT 所有权验证
220
+ - **HTTP 触发器** —— 使用 HTTP 方法与路径定义触发器,并指定后端函数
221
+ - **自定义域名** —— 阿里云 OSS 与 API 网关自动完成 CNAME + DNS TXT 所有权验证;腾讯云通过 DNSPod 托管域名
151
222
  - **CDN 加速** —— 为静态站点提供边缘缓存与全球内容分发
152
223
  - **OSS 传输加速** —— 通过阿里云骨干网进行跨区域数据传输
224
+ - **腾讯云函数 URL** —— 无需独立网关资源即可提供 HTTP 入口
153
225
 
154
226
  ### 定时触发器
155
227
 
@@ -164,34 +236,75 @@ functions:
164
236
  cron: '0 23 3 * * *' # 必填 —— si-cron,按 UTC 解释
165
237
  payload: '{"job":"billing-run"}' # 可选,原样透传
166
238
  enable: true # 可选,默认 true
167
- description: 每日出账 # 可选
239
+ description: 每日出账 # 可选
168
240
  - name: report-hourly
169
241
  cron: '@every 1h'
170
242
  ```
171
243
 
172
- `cron` 支持标准 5 段表达式(`分 时 日 月 周`)、带秒前缀的 6 段,或
173
- `@every <时长>`(`30s`、`5m`、`1h`、`1d` 等)。si-cron 一律按 **UTC** 解释——
174
- 合成层负责翻译成各家方言(阿里云 FC3 六段、腾讯云 SCF 含年的七段、火山引擎
175
- veFaaS 五段 crontab),并完成 UTC+8 字段平移,因此同一份 YAML 在所有云平台
176
- 触发时刻一致。非法表达式与平台能力上限(腾讯云 SCF 单函数最多 10 个定时触发器)
177
- 在 `si validate` 阶段即报错,不会进入部署。
244
+ `cron` 支持标准 5 段表达式(`分 时 日 月 周`)、带秒前缀的 6 段,或 `@every <时长>`(`30s`、`5m`、`1h`、`1d` 等)。si-cron 一律按 **UTC** 解释——合成层负责翻译成各家方言(阿里云 FC3 六段、腾讯云 SCF 含年的七段、火山引擎 veFaaS 五段 crontab),并完成 UTC+8 字段平移,因此同一份 YAML 在所有云平台触发时刻一致。非法表达式与平台能力上限(腾讯云 SCF 单函数最多 10 个定时触发器)在 `si validate` 阶段即报错,不会进入部署。
245
+
246
+ <details>
247
+ <summary><b><code>triggers</code> 与顶层 <code>events</code> 的区分</b></summary>
178
248
 
179
- **`functions.*.triggers` 与顶层 `events` 的区分**:`triggers`(http、timer)
180
- 是「调用本函数的东西」——函数级归属、随函数级联删除、没有独立配置面。顶层
181
- `events`(如 `API_GATEWAY`)是拥有独立配置面的基础设施资源——自定义域名、
182
- 证书、路由表——删除后端函数后它们依然存在。经验法则:有独立配置面 →
183
- `events`;纯调度/事件绑定 → `triggers`。
249
+ `functions.*.triggers`(http、timer)是「调用本函数的东西」——函数级归属、随函数级联删除、没有独立配置面。顶层 `events`(如 `API_GATEWAY`)是拥有独立配置面的基础设施资源——自定义域名、证书、路由表——删除后端函数后它们依然存在。经验法则:有独立配置面 → `events`;纯调度/事件绑定 → `triggers`。
250
+
251
+ </details>
184
252
 
185
253
  ### 资源管理
186
254
 
187
- 不止于函数——管理包含存储、数据库等在内的完整 Serverless 技术栈。
255
+ 不止于函数——管理包含存储、数据库与数据表在内的完整 Serverless 技术栈。
188
256
 
189
257
  - **对象存储** —— OSS(阿里云)、COS(腾讯云)、TOS(火山引擎)
190
- - **数据库** —— RDS、OTS、ESS、TDSQL-C,更多陆续支持
191
- - **Elasticsearch Serverless** —— 部署并管理 ES 集群
192
- - **GPU 函数** —— 部署支持 GPU 的 Serverless 函数
193
-
194
- ### 架构
258
+ - **数据库** —— RDS MySQL Serverless、TDSQL-C 与 Elasticsearch Serverless
259
+ - **数据表** —— 阿里云 TableStore
260
+ - **GPU 函数** —— 在阿里云部署支持 GPU 的 Serverless 函数
261
+
262
+ ## 支持的云服务商
263
+
264
+ | 云服务商 | 函数 | HTTP 入口 | 对象存储 | 数据库与数据表 | 状态 |
265
+ | ---------------- | -------------------------- | ---------------------- | -------- | ------------------------------------------------------------- | ------ |
266
+ | **阿里云** | ✅ FC3 | ✅ API 网关 | ✅ OSS | ✅ RDS MySQL Serverless、TableStore、Elasticsearch Serverless | 稳定 |
267
+ | **腾讯云** | ✅ SCF | ✅ 函数 URL 触发器 | ✅ COS | ✅ TDSQL-C、Elasticsearch Serverless | 稳定 |
268
+ | **火山引擎** | ✅ veFaaS | ✅ API 网关 | ✅ TOS | — | 稳定 |
269
+ | **华为云** | ⚠️ 仅生成 Terraform 模板 | — | — | — | 预览 |
270
+ | **AWS** | — | — | — | — | 计划中 |
271
+ | **Azure** | — | — | — | — | 计划中 |
272
+ | **Google Cloud** | — | — | — | — | 计划中 |
273
+
274
+ 说明:
275
+
276
+ - 华为云配置可被解析并生成 Terraform HCL 模板,但部署能力尚未实现。
277
+ - 腾讯云没有独立的 API 网关资源,HTTP 入口由函数 URL 触发器提供。
278
+ - 火山引擎暂不支持 Serverless 数据库与数据表。
279
+ - 资源级细节见[完整支持矩阵](https://serverlessinsight.com/reference.html)。
280
+
281
+ ## 文档
282
+
283
+ | 资源 | 链接 |
284
+ | ---------------- | ------------------------------------------------------------- |
285
+ | 快速入门 | <https://serverlessinsight.com/getting-started.html> |
286
+ | 配置参考 | <https://serverlessinsight.com/reference.html> |
287
+ | CLI 参考 | <https://serverlessinsight.com/cli.html> |
288
+ | JSON Schema | `si schema`(自包含 draft-07) |
289
+ | 本地开发 | [docs/local-development.md](docs/local-development.md) |
290
+ | Deployment state | [docs/regional-deployment-state.md](docs/regional-deployment-state.md) |
291
+ | 状态锁 | [docs/state-locking.md](docs/state-locking.md) |
292
+ | 架构决策记录 | [docs/adr](docs/adr) |
293
+ | 示例 | [samples](samples) |
294
+ | 更新日志 | [CHANGELOG.md](CHANGELOG.md) |
295
+ | 常见问题 | <https://serverlessinsight.com/faq.html> |
296
+
297
+ ## 路线图
298
+
299
+ - 华为云函数部署(模板生成已就绪)
300
+ - AWS、Azure 与 Google Cloud 支持
301
+ - 腾讯云独立 API 网关资源
302
+ - 火山引擎 Serverless 数据库与数据表
303
+ - 更多 Serverless 资源与厂商能力
304
+
305
+ 路线图仅表示方向,不构成承诺。欢迎通过 Issue 讨论优先级。
306
+
307
+ ## 架构
195
308
 
196
309
  ServerlessInsight 采用**函数式客户端架构**,将云厂商 SDK 与业务逻辑清晰分离:
197
310
 
@@ -203,27 +316,29 @@ ServerlessInsight 采用**函数式客户端架构**,将云厂商 SDK 与业
203
316
  ↓
204
317
  ┌─────────────────────────────────────────┐
205
318
  │ Functional Client Layer │ ← 封装的 SDK 操作
206
- │ (aliyunClient.ts, tencentClient.ts) │
319
+ │ (aliyunClient、tencentClient、 │
320
+ │ volcengineClient) │
207
321
  └─────────────────────────────────────────┘
208
322
  ↓
209
323
  ┌─────────────────────────────────────────┐
210
- │ Cloud Provider SDKs │ ← @alicloud/*, tencentcloud-*
324
+ │ Cloud Provider SDKs │ ← @alicloud/*、tencentcloud-*、@volcengine/*
211
325
  └─────────────────────────────────────────┘
212
326
  ```
213
327
 
214
328
  - **函数式且纯粹** —— 业务逻辑使用不可变数据的纯函数
215
329
  - **SDK 封装** —— 云厂商 SDK 仅能通过客户端模块访问
216
- - **无类** —— 优先使用 `type` 而非 `interface`,优先采用函数式模式而非类
330
+ - **函数式优先** —— 优先使用 `type` 而非 `interface`,优先函数而非类,采用声明式集合处理
217
331
 
218
332
  ## 开发
219
333
 
220
- ServerlessInsight 基于 [Node.js](https://nodejs.org/) + [TypeScript](https://www.typescriptlang.org/)、[Commander.js](https://github.com/tj/commander.js/) CLI 构建,采用纯函数式架构。
334
+ ServerlessInsight 基于 [Node.js](https://nodejs.org/) + [TypeScript](https://www.typescriptlang.org/)、[Commander.js](https://github.com/tj/commander.js/) CLI 构建,采用函数式架构。
221
335
 
222
336
  ### 前置要求
223
337
 
224
- - **Node.js** >= 16
338
+ - **Node.js** >= 22.12
339
+ - **npm**(随 Node.js 附带)
225
340
 
226
- ### 快速开始
341
+ ### 从源码构建
227
342
 
228
343
  ```bash
229
344
  git clone https://github.com/geek-fun/serverlessinsight.git
@@ -235,46 +350,44 @@ npm link
235
350
 
236
351
  ### 脚本
237
352
 
238
- | 命令 | 说明 |
239
- | ------------------ | -------------------- |
240
- | `npm run build` | TypeScript 编译 |
241
- | `npm test` | 运行全部测试(含覆盖率) |
242
- | `npm run test:unit` | 仅单元测试 |
243
- | `npm run test:service` | 仅服务测试 |
244
- | `npm run lint:check` | ESLint 检查 |
245
- | `npm run lint:fix` | 自动修复 lint 问题 |
246
-
247
- ### 示例配置
248
-
249
- ```yaml
250
- version: 0.0.1
251
- provider:
252
- name: aliyun
253
- region: cn-hongkong
353
+ | 命令 | 说明 |
354
+ | ---------------------- | ---------------------- |
355
+ | `npm run build` | TypeScript 编译 |
356
+ | `npm test` | 运行全部测试(含覆盖率) |
357
+ | `npm run test:unit` | 仅单元测试 |
358
+ | `npm run test:service` | 仅服务测试 |
359
+ | `npm run test:ci` | CI 测试运行 |
360
+ | `npm run lint:check` | ESLint 检查 |
361
+ | `npm run lint:fix` | 自动修复 lint 问题 |
254
362
 
255
- service: my-api-service
363
+ 测试分为两类:完全隔离并 Mock 外部依赖的快速单元测试,以及运行真实 parser、planner、executor 与状态管理器的服务测试。覆盖率门槛为分支、函数、行与语句四项均达到 85%。
256
364
 
257
- functions:
258
- hello_function:
259
- name: hello-world-fn
260
- code:
261
- runtime: nodejs18
262
- handler: index.handler
263
- path: ./src
264
- memory: 512
265
- timeout: 10
365
+ ### 项目结构
266
366
 
267
- events:
268
- api_gateway:
269
- type: API_GATEWAY
270
- name: my-api-gateway
271
- triggers:
272
- - method: GET
273
- path: /api/hello
274
- backend: ${functions.hello_function}
367
+ ```
368
+ src/
369
+ ├── commands/ # CLI 命令处理(deploy、destroy、diff、local 等)
370
+ ├── common/ # 共享工具、客户端、状态与锁管理
371
+ │ ├── aliyunClient/
372
+ │ ├── tencentClient/
373
+ │ └── volcengineClient/
374
+ ├── lang/ # 国际化文案(en.ts、zh-CN.ts)
375
+ ├── parser/ # YAML 解析与校验
376
+ ├── stack/ # 各云厂商资源逻辑
377
+ │ ├── aliyunStack/
378
+ │ ├── scfStack/ # 腾讯云
379
+ │ ├── volcengineStack/
380
+ │ ├── localStack/ # 本地开发服务
381
+ │ └── rfsStack/ # 华为云 Terraform 模板(预览)
382
+ ├── types/ # TypeScript 类型定义
383
+ └── validator/ # JSON Schema 校验
384
+ tests/
385
+ ├── fixtures/ # 测试夹具(YAML 配置、制品)
386
+ ├── unit/ # 隔离的单元测试
387
+ └── service/ # 端到端服务测试
275
388
  ```
276
389
 
277
- 更多示例见 [samples](./samples) 目录。
390
+ 编码规范、测试规则与架构原则见 [AGENTS.md](AGENTS.md)。
278
391
 
279
392
  ## 社区
280
393
 
@@ -292,7 +405,11 @@ events:
292
405
 
293
406
  ## 贡献
294
407
 
295
- 欢迎贡献!提交 Issue 或 Pull Request 即可。编码规范请参见 [AGENTS.md](AGENTS.md)。
408
+ 欢迎贡献——无论是缺陷反馈、功能建议、文档修正还是代码。
409
+
410
+ - 使用[缺陷报告](.github/ISSUE_TEMPLATE/bug_report.md)或[功能建议](.github/ISSUE_TEMPLATE/feature_request.md)模板提交 Issue。
411
+ - 提交 Pull Request 前,请运行 `npm run lint:check`、`npm run build` 与 `npm test`。
412
+ - 遵循 [AGENTS.md](AGENTS.md) 中的约定以及现有的 [Pull Request 模板](.github/PULL_REQUEST_TEMPLATE.md)。
296
413
 
297
414
  ## 赞助
298
415
 
package/codecov CHANGED
Binary file
package/codecov.SHA256SUM CHANGED
@@ -1 +1 @@
1
- ca1d64196d2d34771084afe76ea657d581bf628e31d993ff8e52ea09cc88a56d codecov
1
+ 8e1bfb71661378530f6ea21e82b414095899e565cbb4cf555c613064be17b973 codecov
@@ -1,16 +1,16 @@
1
1
  -----BEGIN PGP SIGNATURE-----
2
2
 
3
- iQIzBAABCgAdFiEEJwNOf9uFDgu8LGL/gGuyiu13mGkFAmpO+3UACgkQgGuyiu13
4
- mGm0UxAAne5/lA7YQHQlWt455twIGwZgcSX13LTQw45+goIfZC7IGDQ7J6/kLyJG
5
- sGvkfSmYEODgsgo6474CWcm16VPMZa3QWa4z6EdfyNHhDo5nNe358ZPA1dOemMKZ
6
- eV2/9WpDcIEIAhsCj8HKjNjsLBcGrAQRbOw2tABg2dbE8Yg94SMdEqjMCswOQn3i
7
- OPsybWDjbAdqUVIWylUXbned5/hVnzNAMeo6WvC5+LNw1iS+8rzSIUu5iSxCz9jV
8
- XBe0ZNZ/z1jLZ0NHQXWoOWVT6aHI3Aml/V+ttduuSPwVqWUtqT+XWnnxXJlkt3fQ
9
- uB8Fy9NBkj5qkls81pUyt0Z9QuMvnI/OxWiUZ6jOEItiZMkK87ryPiheBoaU4kuf
10
- fcpoRz/EVNsAgcrHBFQCiam7I32h5R5O9orDiU4pKzahSdgelnvOPIZQzSKT5m/M
11
- 50tuts7npVQib2op7XCv+6d3t8ZnUHzXnqiej6n/vWxE3nWJiw39a5ww7RDO1RQB
12
- 8oNPX3qvPGpNmspXSf57oLyJqiSs4t7B9yIacCMPnlVDZt3MseXP/UHH7cXMmRuX
13
- bU2mkdieBgkGtkNkB76sp/ob5FWQmynW1+Q3ZcDGrGeysnRgDGWD2Yy92lcABZDc
14
- DXolC9kpvP+UrUXG5XSTIKksMbH4YacgNIKHzwyhOgViMLWBA4g=
15
- =fH2Y
3
+ iQIzBAABCgAdFiEEJwNOf9uFDgu8LGL/gGuyiu13mGkFAmriM1YACgkQgGuyiu13
4
+ mGlz3xAAjA+ezaisBIq/CFzGiqM3DBgyzhtC+1Jzdl4LXQV1a9gumHU0wLS4t91x
5
+ v20z2wrDq35SvClgEFX8zMoM6t7KJrQJ7+kHTtpzLLaHJt8TmxE94ZJZigduaObx
6
+ UjAG/JBEUQ+EVj1q5X5/O4hU/Uw+M+cj+NYSh3FEDSnUSR3mJOdhdvY3hJNAWOtN
7
+ M+oEfXyzMJG1Fcpf2P3vAhV6Dx2OR1RcKgLA2bYp4QwbBMvfGwiqURRR66QDqxWT
8
+ ErjiQsYshGgtPNHFktQjcse3aS7n2DvGI9sn0e+TfcOi3F2sxLz9wV7bFjRaaYG8
9
+ gNGY7BSFSrCStv0a0T3jk5n1DkTsRwMjPlSQEOicsau8Bh2qotwKuvMSkYzmwBOs
10
+ jFohe/KBdnV6wMiqRiXqAPga56gp5Cttf8kT7rRn6aT0uECEwTooeVDkmEeWBsV9
11
+ J7s+r62K1cBA6qIaKjUM603VKGAqmr5629SnXW+elagJnLIevT8czjqItSmECl0R
12
+ huRoUEsGwflwxzgfZU/h+EwU6aPFSbazNFxqNv3/MNGbEVjpihEiKfQnw9jfYauA
13
+ 7wa3bLRRFvZaRBMnDvqYjXoefpPutP2fSPDgFKdDfE0DmC4cA6A45zez42vLcbDr
14
+ yz/kqWUWy5tqgEghGIT8AZysxnqfRwXuzi9uoewGoDMR8pTSahs=
15
+ =ps64
16
16
  -----END PGP SIGNATURE-----
package/dist/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@geek-fun/serverlessinsight",
3
- "version": "0.9.3",
4
- "description": "Full-lifecycle serverless IaC — one open-source platform to develop, deploy and operate serverless across clouds.",
3
+ "version": "0.9.5",
4
+ "description": "Full-lifecycle serverless IaC for Alibaba Cloud, Tencent Cloud and Volcengine — one YAML to define, deploy and operate functions, API gateways, storage and databases.",
5
5
  "homepage": "https://serverlessinsight.com",
6
6
  "main": "dist/src/index.js",
7
7
  "types": "dist/src/index.d.ts",
@@ -29,28 +29,31 @@
29
29
  },
30
30
  "keywords": [
31
31
  "serverless",
32
+ "serverless-framework",
33
+ "serverless-iac",
34
+ "infrastructure-as-code",
35
+ "iac",
36
+ "cli",
37
+ "faas",
38
+ "serverless-functions",
32
39
  "serverless-insight",
33
- "lambda",
34
- "aws-lambda",
35
- "azure-functions",
36
- "google-cloud-functions",
37
- "tencent-cloud-functions",
40
+ "multi-cloud",
41
+ "alibaba-cloud",
42
+ "alibaba-serverless",
38
43
  "alibaba-cloud-functions",
39
- "huawei-cloud-functions",
44
+ "tencent-cloud",
45
+ "tencent-serverless",
46
+ "tencent-cloud-functions",
47
+ "volcengine",
40
48
  "volcengine-cloud-functions",
41
- "serverless-framework",
42
- "serverless-management",
43
- "serverless-automation",
49
+ "serverless-tool",
50
+ "serverless-deploy",
51
+ "serverless-offline",
44
52
  "serverless-observability",
45
53
  "serverless-tracing",
46
- "serverless-offline",
47
- "alibaba",
48
- "tencent",
49
- "azure",
50
- "huawei",
51
- "google",
52
- "volcengine",
53
- "function"
54
+ "api-gateway",
55
+ "typescript",
56
+ "devops"
54
57
  ],
55
58
  "dependencies": {
56
59
  "@alicloud/alidns20150109": "^4.6.0",