bingshuo
/
zhizhi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zhizhi/team-integration-v2/cos-config/bucket-setup-guide.md

8.1 KiB
Raw Blame History

🪣 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) 离你最近的数据中心
访问权限 私有读写 只有你的密钥才能访问
其他选项 全部默认即可 不要勾选多余的东西
  1. 点 "确定" 创建

创建完成后，你会看到桶的完整名字类似：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 相当于密码
  1. ⚠️ 重要：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：配置铸渊桶的写入密钥

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

  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"
函数 选 "新建函数"
  1. 新建的云函数内容，使用本安装包中 cos-config/scf-trigger-template.js 的代码
  2. 在云函数的环境变量中配置：
环境变量名 值
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：不需要。工作流会自动运行。你只需要正常用副驾驶开发代码就行，其他的是自动的。