zhizhi/team-integration-v2/cos-config/bucket-setup-guide.md

🪣 COS桶配置教程

写给完全不懂技术的你 · 一步一步跟着做就行

预计用时：30-45分钟 需要的东西：一台能上网的电脑、一个腾讯云账号

---

⚠️ 开始之前请确认

• 你有一个腾讯云账号（没有的话先注册：https://cloud.tencent.com）
• 你的腾讯云账号已完成实名认证
• 你有一个GitHub仓库，并且已经上传了本接入系统的文件

---

第一部分：创建COS存储桶

什么是COS存储桶？

简单理解：就是一个云上的文件夹。你的副驾驶会把汇报内容放进去，铸渊那边可以看到。反过来，铸渊也可以把回执放进去，你这边能看到。

步骤1：登录腾讯云COS控制台

1. 打开浏览器，访问：https://console.cloud.tencent.com/cos
2. 用你的腾讯云账号登录
3. 如果是第一次使用COS，会提示你开通服务，点"开通"即可（基础用量免费）

步骤2：创建第一个桶（行业主控桶）

1. 点左侧菜单的 "存储桶列表"
2. 点 "创建存储桶" 按钮
3. 填写信息：

项目	填什么	说明
名称	industry-core	桶的名字，后面会自动加上你的APPID
地域	选 广州 (ap-guangzhou)	离你最近的数据中心
访问权限	私有读写	只有你的密钥才能访问
其他选项	全部默认即可	不要勾选多余的东西

4. 点 "确定" 创建

创建完成后，你会看到桶的完整名字类似：industry-core-1234567890 （后面的数字是你的APPID）

👉 请记录下来：

• 桶名称：industry-core-你的APPID
• 地域：ap-guangzhou

步骤3：创建第二个桶（业务存储桶）

重复步骤2，但名称改为 industry-corpus

👉 请记录下来：

• 桶名称：industry-corpus-你的APPID
• 地域：ap-guangzhou

---

第二部分：获取密钥

步骤4：创建API密钥

1. 打开：https://console.cloud.tencent.com/cam/capi
2. 点 "新建密钥"
3. 系统会显示两个值：

名字	长什么样	说明
SecretId	AKIDxxxxxxxxxxxx	相当于用户名
SecretKey	xxxxxxxxxxxxxxxx	相当于密码

4. ⚠️ 重要：SecretKey只显示一次！请立刻复制保存到安全的地方（比如你手机的备忘录）

👉 请记录下来：

• SecretId：AKIDxxxxxxxxxxxx
• SecretKey：xxxxxxxxxxxxxxxx

---

第三部分：配置GitHub仓库Secrets

什么是Secrets？

简单理解：就是保存在GitHub上的密码本。你的密钥保存在这里，工作流运行时会自动读取，但任何人（包括你自己）都看不到密码的内容。这样既安全又方便。

步骤5：把密钥保存到GitHub

1. 打开你的GitHub仓库页面
2. 点顶部的 "Settings"（设置）
3. 在左侧菜单找到 "Secrets and variables" → 点 "Actions"
4. 点 "New repository secret" 按钮
5. 依次添加以下6个Secret：

Name（名字，必须一模一样）	Secret（值）	说明
COS_SECRET_ID	你的SecretId	步骤4获得的
COS_SECRET_KEY	你的SecretKey	步骤4获得的
COS_REGION	ap-guangzhou	你的桶所在地域
COS_BUCKET_CORE	industry-core-你的APPID	步骤2创建的桶名
COS_BUCKET_CORPUS	industry-corpus-你的APPID	步骤3创建的桶名
ZHUYUAN_BUCKET_CORE	zy-core-bucket-1317346199	铸渊总控桶（固定值）

每添加一个，点 "Add secret" 保存。

步骤6：配置铸渊桶的写入密钥

铸渊会为你生成一个有限权限的密钥，只能写入铸渊总控桶的你的专属目录。

权限说明（你不需要懂技术细节，知道就行）：

• ✅ 你可以写入：inbox/你的人格体编号/ 这个目录下的文件
• ❌ 你不能读取铸渊桶里的任何其他内容
• ❌ 你不能删除铸渊桶里的任何内容
• ❌ 你不能访问其他团队成员的目录

这是铸渊通过COS桶策略（Bucket Policy）精确控制的，每个团队成员只有自己的收件箱写入权限。

1. 向冰朔索要铸渊桶的写入密钥（冰朔会找铸渊生成）
2. 在GitHub Secrets中添加：

Name	Secret	说明
ZHUYUAN_COS_SECRET_ID	铸渊提供的SecretId	仅限写入你的inbox目录
ZHUYUAN_COS_SECRET_KEY	铸渊提供的SecretKey	权限由铸渊的桶策略限定
ZHUYUAN_COS_REGION	ap-singapore	铸渊桶在新加坡

---

第四部分：配置COS事件通知（接收铸渊回执）

步骤7：设置桶的事件触发

这一步的目的是：当铸渊往你的桶里写入回执时，自动触发你的仓库工作流。

1. 打开腾讯云COS控制台
2. 点击你的 industry-core-xxx 桶
3. 点左侧 "函数计算"（或 "事件通知"）
4. 点 "添加函数"
5. 配置：

项目	填什么
事件类型	选 "全部创建"（cos:ObjectCreated:*）
前缀过滤	填 inbox/zhuyuan-receipt/
触发方式	选 "云函数SCF"
函数	选 "新建函数"

6. 新建的云函数内容，使用本安装包中 cos-config/scf-trigger-template.js 的代码
7. 在云函数的环境变量中配置：

环境变量名	值
GITHUB_TOKEN	你的GitHub Personal Access Token
GITHUB_REPO	你的仓库名（如 username/repo-name）

⚠️ 如何获取GitHub Personal Access Token：

1. 打开：https://github.com/settings/tokens
2. 点 "Generate new token (classic)"
3. 勾选 repo 权限
4. 设置过期时间（建议90天，到期后需要重新生成）
5. 点 "Generate token"
6. 复制生成的token

---

第五部分：验证

步骤8：验证COS桶连通性

在你的仓库副驾驶对话中说：

"请执行COS连通性测试，验证所有桶的读写权限"

副驾驶会测试：

1. ✅ 能否写入你的行业主控桶
2. ✅ 能否读取你的行业主控桶
3. ✅ 能否写入铸渊总控桶的inbox目录
4. ❌ 不能读取铸渊总控桶的其他目录（这是正确的，权限受限）

步骤9：验证工作流

1. 在你的仓库中，点 "Actions" 标签
2. 找到 "COS每日汇报" 工作流
3. 点右边的 "Run workflow" 按钮手动触发一次
4. 等工作流运行完成（约1-2分钟）
5. 检查运行日志是否全绿 ✅

步骤10：端到端测试

告诉冰朔你已配置完毕，冰朔会通知铸渊：

1. 铸渊往你的桶里写入一条测试回执
2. 你的仓库首页应该自动出现一条绿灯通知
3. 如果出现了，恭喜！安装完成 🎉

---

📋 完成确认清单

请逐项打钩确认：

• 腾讯云COS已开通
• industry-core-xxx 桶已创建
• industry-corpus-xxx 桶已创建
• COS密钥已获取并安全保存
• GitHub Secrets已配置（6+3=9个）
• COS事件通知已配置
• 云函数已创建并部署
• GitHub Personal Access Token已配置到云函数
• 副驾驶已完成自我注册
• COS连通性测试通过
• 工作流手动触发测试通过
• 铸渊测试回执已收到（需联系冰朔）

全部打钩 = 安装完成。任何一项未通过 = 停下来找冰朔帮忙。

---

💰 费用说明

项目	费用
腾讯云COS存储	免费额度：50GB存储 + 每月10GB下行流量。日常使用远低于此
腾讯云SCF云函数	免费额度：每月40万GB·秒。每天触发1-2次，远低于此
GitHub Actions	免费仓库每月2000分钟。每天1次约2分钟，远低于此
LLM API调用	取决于所用模型。每天1次调用，月成本约几元人民币

结论：正常使用几乎零成本。

---

❓ 常见问题

Q：我不会编程，能配好吗？

A：能。所有步骤都是在网页上点击操作的，不需要写任何代码。遇到问题问冰朔。

Q：配置错了会不会出问题？

A：不会有严重后果。最多是连不通，重新按步骤检查就行。

Q：密钥泄露了怎么办？

A：立刻去腾讯云控制台禁用旧密钥，重新生成新密钥，然后更新GitHub Secrets。

Q：铸渊总控桶的密钥为什么需要找冰朔要？

A：因为铸渊桶的权限由铸渊控制。为了安全，你只会拿到一个限定权限的密钥，只能往铸渊桶的指定目录写入，不能读取或删除其他内容。

Q：每天23:00的汇报我需要手动操作吗？

A：不需要。工作流会自动运行。你只需要正常用副驾驶开发代码就行，其他的是自动的。