前置条件
CNB Token
需要以下权限的 Token：
| 权限 | 说明 | 最小权限 |
|---|---|---|
repo-pr:rw | 创建/合并 PR | ✅ 必选 |
repo-code:rw | 读写仓库代码 | ✅ 必选（含 work_mode） |
repo-admin:rw | 仓库管理（转移/删除） | ✅ 必选 |
group-admin:rw | 组织管理（关闭保护） | ✅ 必选 |
org-npc:npc | NPC 调度 | ✅ 必选 |
bash
export CNB_TOKEN="your_token_here"腾讯云凭证
| 工具 | 用途 | 获取方式 |
|---|---|---|
SecretId + SecretKey | CloudBase CLI / SDK 认证 | 腾讯云控制台 → 访问管理 → API 密钥 |
~/.tccli/default.credential | tcb CLI 凭证文件 | tcb login 自动生成，切勿提交到仓库 |
bash
# 方式一：tcb login（推荐）
tcb login
# 方式二：显式传参
tcb login --apiKeyId $SECRET_ID --apiKey $SECRET_KEY工具依赖
| 工具 | 版本要求 | 用途 | 安装方式 |
|---|---|---|---|
node | ≥18 | 前端构建 | nvm install 18 |
npm | ≥9 | 包管理 | 随 node 安装 |
tcb | latest | CloudBase CLI | npm i -g @cloudbase/cli |
edgeone | ≥1.2.30 | EdgeOne Pages 部署 | npm i -g edgeone@latest |
git | ≥2.30 | 版本控制 | 系统自带 |
curl | ≥7.68 | API 调用 | 系统自带 |
python3 | ≥3.8 | 配置解析 | 系统自带或 brew install python |
环境预检
bash
bash check-env.sh脚本自动检查：
- ✅ CNB_TOKEN 已设置
- ✅ 目标组织存在且有写入权限
- ✅ CNB API 可访问
- ✅ 工具链版本达标（tcb / edgeone / node / npm）
- ✅ 凭证文件未意外提交
仓库结构约定
流水线完成后，仓库应包含：
{项目名}/
├── PRD.md # 产品需求文档（用户端+管理后台）
├── mockups/ # UI 设计稿 SVG
│ ├── page-home.svg # 用户端页面（375×812px）
│ ├── ...
│ ├── admin-dashboard.svg # 管理后台（1440×900px）
│ └── ...
├── client/ # 用户端前端
│ ├── src/pages/ # 页面组件
│ ├── src/api/ # API 封装（try-catch fallback）
│ ├── public/
│ │ └── _routes.json # SPA fallback
│ └── package.json
├── admin/ # 管理后台前端
│ ├── vite.config.ts # base: '/admin/'
│ ├── src/pages/
│ ├── public/
│ │ └── _routes.json
│ └── package.json
├── server/ # CloudBase 云函数
│ ├── api-xxx/
│ │ └── index.js
│ ├── admin-dashboard/
│ │ └── index.js
│ └── types/ # 共享类型定义
├── cloudbaserc.json
└── README.md安全最佳实践
| # | 规则 | 说明 |
|---|---|---|
| 1 | 不提交凭证 | .gitignore 已包含 .tccli、.env、cloudbaserc.local.json |
| 2 | Token 最小权限 | 只用 repo-*:rw + group-admin:rw + org-npc:npc，不要用 super admin Token |
| 3 | 定期轮换 Token | 建议每 90 天换一次 |
| 4 | 不硬编码环境 ID | cloudbaserc.json 用占位符，部署时替换 |
| 5 | .cnb/settings.yml | 不要写入敏感信息，该文件在公开仓库中可见 |