OSS 存储微服务¶

src/storage/ 是独立的 阿里云 OSS 上传/下载微服务（默认端口 8002）。OSS AccessKey 仅存在于该服务，backend / myapp 不持有 OSS 密钥，通过 HTTP 调用 storage。

设计目标¶

原则	说明
密钥隔离	`OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` 只在 `src/storage/.env` 或 K8s `harness-storage-secrets`
统一 HTTP 出口	backend 经 `src/backend/utils/storage_client.py` 调用，禁止直接 import OSS SDK
独立扩缩容	storage 与 backend 分 Deployment，可单独重启/升级

目录结构¶

路径	用途
`storage/api/objects.py`	预签名上传/下载、对象元数据 API
`storage/api/health.py`	存活/就绪探针
`storage/core/services/oss_service.py`	OSS 业务逻辑
`storage/utils/oss_client.py`	阿里云 OSS SDK 封装
`storage/config.py`	`Settings`（`OSS_*`、`CORS_ORIGINS`）
`storage/composition/`	FastAPI Depends 注入

调用关系¶

flowchart LR
  subgraph clients [调用方]
    Canvas[Infinite Canvas 前端]
    Backend[backend API]
  end
  subgraph storage_svc [storage :8002]
    API["/api/objects/*"]
    OSS[(阿里云 OSS)]
  end
  Canvas -->|"/api/storage"| API
  Backend -->|STORAGE_SERVICE_URL| API
  API --> OSS

Canvas 前端：Ingress 将 /api/storage 代理到 storage Service
backend：ConfigMap 中 STORAGE_SERVICE_URL=http://storage:8002（K8s 集群内 DNS）

主要 API¶

方法	路径	说明
GET	`/health/live`	存活探针
GET	`/health/ready`	就绪探针
POST	`/api/objects/presign-upload`	获取预签名上传 URL
POST	`/api/objects/presign-download`	获取预签名下载 URL

响应格式与 backend 一致，使用 {code, message, data} 包络。

环境变量¶

配置模板：src/storage/.env.example

变量	说明
`OSS_ENABLED`	是否启用 OSS（`false` 时可用于本地 mock）
`OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET`	RAM 凭证（勿提交 git）
`OSS_BUCKET`	Bucket 名称
`OSS_ENDPOINT`	如 `oss-cn-hangzhou.aliyuncs.com`
`OSS_PREFIX`	对象键前缀，如 `canvas/refs/`
`OSS_PUBLIC_BASE_URL`	可选，CDN 或自定义域名
`OSS_PRESIGN_UPLOAD_EXPIRES`	上传预签名有效期（秒）
`OSS_PRESIGN_DOWNLOAD_EXPIRES`	下载预签名有效期（秒）
`CORS_ORIGINS`	允许的前端来源（JSON 数组）

backend 侧只需：

变量	说明
`STORAGE_SERVICE_URL`	本地 `http://127.0.0.1:8002`；K8s `http://storage:8002`

本地开发¶

# 终端 1：storage
make run-storage

# 终端 2：backend（需 STORAGE_SERVICE_URL 指向 :8002）
make run-backend

Kubernetes 部署¶

环境	Ingress 主机	storage Service
K3s	`http://upload.localhost`	`storage.harness-app.svc:8002`
ACK	`http://upload.harness.local`	同上

Secret 生成：

K3s：deploy/k3s/scripts/create-secrets.ps1 读取 src/storage/.env
ACK：deploy/ACK/scripts/create-secrets.ps1 同上

清单：deploy/k3s/base/storage/（Deployment、Service、ConfigMap）。