241 lines
8.1 KiB
Markdown
241 lines
8.1 KiB
Markdown
# 🪣 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：配置铸渊桶的写入密钥
|
||
|
||
铸渊会为你生成一个**有限权限的临时密钥**，只能写入铸渊总控桶的指定目录。
|
||
|
||
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：不需要。工作流会自动运行。你只需要正常用副驾驶开发代码就行，其他的是自动的。
|