对象存储（腾讯云 COS）

​

为什么用对象存储

• 数据库瘦身：音频字节从 media_objects.data 迁出后，表里只保留 storage_key、cache_hash 等元数据，rakull_data 的 pg_dump 备份与恢复更快。
• 跨实例共享：多实例部署时所有 data_server 指向同一个 COS 桶，TTS 音频天然去重。
• 生命周期管理：通过 COS 控制台配置 tmp/ 前缀的过期规则（例如 7 天自动删除）即可清理临时文件。
• 与现有开发流程兼容：本地开发仍默认走 local，无需 COS 凭证即可跑全部测试。

​

配置

OBJECT_STORE=cos \
COS_SECRET_ID= \
COS_SECRET_KEY= \
COS_REGION=ap-shanghai \
COS_BUCKET= \
uv run uvicorn app.main:app --port 8014

​

从管理后台配置与探测

​

命令行完整审计与安全清理

bash scripts/stop_all_servers.sh
./scripts/db_snapshot.sh audit-media --source local --output /safe/path/cos-audit.json

./scripts/db_snapshot.sh prune-media --source local \
  --report /safe/path/cos-audit.json \
  --temporary-older-than-days 7 --apply

​

Key 架构

{type}/{scope}/{business}/{...details...}{ext}

​

内容寻址音频缓存

• 多篇文章出现同一句子 + 同一声优 → 数据库只保留一个 media_objects 行，COS 只保留一个对象，TTS 不会重复生成，COS 不会重复上传。
• 情景训练中相同 NPC 台词重复出现时同理。
• media_objects.cache_hash 列上建有部分索引（WHERE cache_hash IS NOT NULL），命中时 O(1) 复用。

​

用户上传与转写生命周期

1. POST /api/videos/file 把音频/视频写入 tmp/u{uid}/transcription/...，返回 file_handle。
2. POST /api/videos/upload 只提交 input_handle；input_path 仅在 data_server 确认为 local 后端时兼容。
3. 转写前 data_server 生成 10 分钟签名 URL。agent_server 还要求用户 Bearer 与 Controller 短期断言同时匹配，并只下载配置的 COS HTTPS 主机。
4. 下载禁止重定向，限制声明大小和实际流大小，并拒绝解析到内网或环回地址的主机；Agent 转写后删除自己的临时文件。
5. 任务成功且 keep_audio=true 时对象移动到 audio|video/u{uid}/sources/...，handle 写入文章 metadata.source_media；否则删除。失败或取消也会尽力删除，tmp/ 的 7 天生命周期作为最终兜底。

TRANSCRIBE_SOURCE_HOSTS:
  - bucket-appid.cos.ap-shanghai.myqcloud.com
MAX_TRANSCRIBE_SIZE_MB: 500

​

仓储内事务 API

1. Standalone 方法（put_media、get_bytes、delete 等）：内部自己开连接、提交事务，适合句子仓储等简单场景。
2. conn_* 事务内方法（conn_insert_media、conn_replace_media、conn_get_bytes、conn_find_by_cache_hash、conn_delete）：接收调用方传入的 DB connection，不自行 commit，适合像 scenario_repo 这种在同一连接事务里连续写入多行、最后统一 commit / 异常 rollback 的仓储，保证“插入 media 行 + 写业务行”在同一 PostgreSQL 事务里原子生效。

1. 在事务内 INSERT 一行占位（data=NULL, storage_key=NULL, cache_hash=?）；
2. 用 media_key(kind, cache_hash, content_type, voice_id=...) 算出 key；
3. 同步 PUT 对象到 COS；
4. UPDATE 该行写入 storage_key；
5. 返回，由调用方 commit。

​

数据迁移

cd rakull_server/data_server

# 1. 预览并生成不含密钥的清单（不会写入 COS 或改 DB）
uv run python scripts/migrate_to_cos.py --dry-run --manifest /safe/path/cos-dry-run.json

# 2. 停服、用 pg_dump 备份 rakull_data 后执行迁移
uv run python scripts/migrate_to_cos.py --manifest /safe/path/cos-cutover.json

• 映射先行、失败关闭：句子音频必须找到唯一的 sentence/audio_voice；情景音频必须找到唯一的 source_text_hash/voice_id，且 64 位 hash 与 content_type 与资产行一致。缺失或冲突会在修改数据库前停止。启动时还会确认 media_objects 已具备 cache_hash 列，否则拒绝执行（先初始化当前 schema）。
• 配置一致：迁移与服务、快照命令读取同一套管理台运行时配置优先级，数据库连接使用 DATA_DATABASE_URL，不需要把管理台密钥再复制到命令行。
• 规范对象优先：同一逻辑 key 已在 COS 时保留并回读该对象；否则旧字节内容不一致时只接受严格多数 SHA-256，平票保持失败关闭并写入清单。
• 分阶段校验：所有分组先解析完毕才开始上传；先上传全部对象，再从 COS 回读并逐项比较大小与 SHA-256；全部通过后才继续。
• 单事务切换：所有 storage_key/cache_hash 更新和 data=NULL 在单个 PostgreSQL 事务中提交（每行校验 rowcount=1），任一行失败即整体回滚。
• 幂等重跑：已经位于 canonical key 的对象仍会被回读校验，不会因重复运行破坏引用。
• 历史上传不猜所有者：本地 UPLOAD_DIR 中的未知文件保持原样，并以 unresolved-owner-kept-local 写入清单。

psql "$DATA_DATABASE_URL" -c \
"SELECT count(*) AS total,
        count(*) FILTER (WHERE data IS NULL AND storage_key IS NOT NULL) AS cos_backed,
        count(*) FILTER (WHERE data IS NOT NULL) AS inline_blobs
 FROM media_objects;"

​

生产切换顺序

1. 禁用任何已公开的旧密钥，为同一个受限 CAM 子用户生成新密钥；先用隔离前缀验证 Put/Get/Head/签名 URL/Delete。
2. 运行 dry-run 并检查清单；任何缺失映射或未知所有者都先处理，不要带警告切换。
3. 停止六个服务（bash scripts/stop_all_servers.sh），用 pg_dump 自定义格式备份 rakull_data，再用 pg_restore --list 验证转储可读：
   pg_dump --format=custom --no-owner --no-privileges \
     --file /safe/path/rakull_data-cutover.pgdump "$DATA_DATABASE_URL"
   pg_restore --list /safe/path/rakull_data-cutover.pgdump >/dev/null
   
   迁移不写 rakull_collection，但如需一致性全集也可同时备份该库。注意 ./scripts/db_snapshot.sh push 会校验所有媒体行都已指向 COS，不能用于迁移前备份；它是切换成功后的快照打包工具。
4. 执行迁移；只接受全部对象大小和 SHA-256 校验通过、脚本输出事务切换完成、清单条目标记为 committed 的结果。
5. 在服务器 gitignored .env 中设置 OBJECT_STORE=cos 和轮换后的凭证，配置 Agent 精确主机白名单，重建并启动服务。
6. 冒烟旧句子音频、情景音频、普通上传和转写上传；确认新字节写入 COS（media_objects.data 为 NULL）而非本地 UPLOAD_DIR，并用上面的 psql 查询复核。

bash scripts/stop_all_servers.sh
pg_restore --clean --if-exists --no-owner --no-privileges \
  --dbname "$DATA_DATABASE_URL" /safe/path/rakull_data-cutover.pgdump

​

端到端验证

cd rakull_server/data_server
OBJECT_STORE=cos uv run python scripts/e2e_cos_sanity.py

OBJECT_STORE=cos uv run pytest -q -m "not integration" --ignore=tests/integration_test

​

运维建议

• 桶安全：桶保持私有并启用 SSE-COS 默认加密；应用只通过短期签名 URL 读取私有对象。
• 生命周期：为 tmp/ 配置 7 天过期，为未完成分块上传配置 1 天清理；永久媒体不设置自动过期。
• 桶权限：CAM 子账户仅授予目标桶所需的 cos:PutObject、cos:GetObject、cos:DeleteObject、cos:HeadObject 与管理端列表所需的 cos:GetBucket；不要授予删桶或其他云资源权限。
• 备份：启用 COS 版本控制或跨地域复制以应对误删；PostgreSQL 双库（至少包含 media_objects 的 rakull_data）需定期用 pg_dump -Fc 备份，或切换完成后用 ./scripts/db_snapshot.sh push 生成经回读校验的快照包，因为数据库持有 storage_key 等权威元数据。
• 切回本地：把 OBJECT_STORE 改回 local 后，新写入的字节会内联到 media_objects.data BYTEA；但已迁移行 storage_key 非空而 data 为 NULL，local 后端只读 data 列，历史音频会读不到。生产回滚不要只翻开关，应按上文用 pg_restore 恢复迁移前快照再以 local 启动。

​

相关模块