modify: S3对象存储
This commit is contained in:
+90
-5
@@ -315,7 +315,91 @@ cd /app
|
||||
|
||||
---
|
||||
|
||||
## 5. 隔离性约束
|
||||
## 5. 文件传输：直连 S3/Minio 对象存储（不依赖网关）
|
||||
|
||||
进程插件可直接对接 S3/Minio 对象存储做文件传输——上传、下载、删除、预签名 URL
|
||||
均由**插件自己的配置**（`[workers.config.storage]`）驱动，**数据路径不经过网关**
|
||||
（预签名 URL 模式下网关甚至不参与数据传输：设备/浏览器拿到 URL 后直传/直取 Minio）。
|
||||
|
||||
### 5.1 配置
|
||||
|
||||
```toml
|
||||
# config/workers/<name>/config.toml
|
||||
[workers.config.storage]
|
||||
endpoint = "192.168.1.10:9000" # Minio 地址 host:port（不带协议前缀）
|
||||
access_key = "minioadmin"
|
||||
secret_key = "minioadmin"
|
||||
bucket = "chongming-files"
|
||||
secure = false # false=http（默认），true=https
|
||||
region = "" # 可选
|
||||
auto_create_bucket = true # 可选，默认 true：启动时确保 bucket 存在
|
||||
```
|
||||
|
||||
语义（`chongming_worker.storage.StorageClient.from_config`）：
|
||||
|
||||
| 情形 | 行为 |
|
||||
| ---- | ---- |
|
||||
| 未配置 / `enabled = false` | 存储关闭（`self.storage = None`），端点自行降级 |
|
||||
| 配置段存在但缺必填键（endpoint/access_key/secret_key/bucket） | **启动硬失败**（ValueError），快速反馈配置错误 |
|
||||
| 连接失败 / bucket 不可用 | 告警降级为 None（不影响其他端点） |
|
||||
|
||||
### 5.2 SDK 用法
|
||||
|
||||
基类在 `_bootstrap` 阶段检测到 `config["storage"]` 段即自动初始化
|
||||
`self.storage`（无需任何额外代码）；插件在 `on_init` 发布到 global_var 供路由读取：
|
||||
|
||||
```python
|
||||
class DemoPlugin(Plugin):
|
||||
async def on_init(self):
|
||||
if self.storage is not None: # 配置了 storage 段才初始化
|
||||
self.set_var("storage", self.storage)
|
||||
```
|
||||
|
||||
路由内使用（同步核心 + async 包装，RPC handler 直接 await）：
|
||||
|
||||
```python
|
||||
from ..global_var import require
|
||||
|
||||
storage = require("storage")
|
||||
await storage.aput_bytes("dir/file.txt", data) # 上传字节
|
||||
await storage.aput_file("dir/file.txt", "/tmp/a.txt") # 上传本地文件
|
||||
data = await storage.aget_bytes("dir/file.txt") # 下载字节
|
||||
await storage.aget_file("dir/file.txt", "/tmp/b.txt") # 下载到本地文件
|
||||
url = await storage.apresigned_put_url("dir/file.txt") # 预签名 PUT（设备直传）
|
||||
url = await storage.apresigned_get_url("dir/file.txt") # 预签名 GET（设备直取）
|
||||
await storage.adelete("dir/file.txt") # 删除
|
||||
```
|
||||
|
||||
API 一览（`chongming_worker.storage.StorageClient`）：
|
||||
|
||||
| 方法（async 同名加 `a` 前缀） | 说明 |
|
||||
| ---- | ---- |
|
||||
| `put_file(object_key, local_path, content_type=None)` | 上传本地文件（fput_object） |
|
||||
| `put_bytes(object_key, data, content_type=None)` | 上传内存字节 |
|
||||
| `get_file(object_key, local_path)` | 下载到本地文件 |
|
||||
| `get_bytes(object_key)` | 下载为字节 |
|
||||
| `delete(object_key)` | 删除对象 |
|
||||
| `presigned_put_url(object_key, expires=3600)` | 预签名 PUT URL（默认 1 小时） |
|
||||
| `presigned_get_url(object_key, expires=3600)` | 预签名 GET URL（默认 1 小时） |
|
||||
|
||||
### 5.3 参考示例
|
||||
|
||||
`workers/demo` 演示了 4 个文件传输端点（`config/workers/demo/` 下对应 TOML）：
|
||||
|
||||
- `POST /demo/presign_upload` — filename → object_key + 预签名 PUT URL（设备直传）
|
||||
- `GET /demo/presign_download` — object_key → 预签名 GET URL（设备直取）
|
||||
- `POST /demo/upload_bytes` — base64 小文件经 Zenoh RPC 上传（大文件请用预签名直传）
|
||||
- `GET /demo/download_bytes` — base64 小文件经 Zenoh RPC 下载
|
||||
|
||||
配置后重启 worker 即可用；未配置时这些端点返回「storage 未配置」错误（降级演示）。
|
||||
|
||||
> 依赖：minio SDK 随 `chongming-worker` 一起安装（utils/worker pyproject 已声明），
|
||||
> 进程插件无需额外 `requirements.txt`。SDK 侧 `chongming_worker.storage` 不依赖网关包，
|
||||
> 隔离性约束与打包流程均不受影响。
|
||||
|
||||
---
|
||||
|
||||
## 6. 隔离性约束
|
||||
|
||||
进程插件**禁止 import `chongming`（网关包）**，只允许依赖：
|
||||
|
||||
@@ -331,7 +415,7 @@ cd /app
|
||||
|
||||
---
|
||||
|
||||
## 6. 进程内契约校验
|
||||
## 7. 进程内契约校验
|
||||
|
||||
Worker 进程启动时自读 TOML 并**在自己进程内**做三方一致性校验
|
||||
（`chongming_worker.contracts.validate_worker_contracts`），校验失败直接退出：
|
||||
@@ -346,7 +430,7 @@ Worker 进程启动时自读 TOML 并**在自己进程内**做三方一致性校
|
||||
|
||||
---
|
||||
|
||||
## 7. 常见问题排查
|
||||
## 8. 常见问题排查
|
||||
|
||||
| 现象 | 原因 / 处理 |
|
||||
| ---- | ----------- |
|
||||
@@ -356,11 +440,12 @@ Worker 进程启动时自读 TOML 并**在自己进程内**做三方一致性校
|
||||
| 路由没出现 | worker 是否就绪（日志「路由发布完成」）；网关 RouteRegistry 是否订阅（启动流程 5.1）；每 10s 自愈重发布，稍等或重启 worker |
|
||||
| 路由一直 404 | worker 是否已退出（优雅退出会摘除路由）；进程被 SIGKILL 时描述符残留，重启 worker 后重发布自愈覆盖 |
|
||||
| 找不到插件配置 | `worker_serve` 须在项目根目录下运行（读 `config/workers/<name>/config.toml`，`--config` 可指定全局配置路径） |
|
||||
| storage.* 端点报「storage 未配置」 | 插件 config.toml 未配置 `[workers.config.storage]`（或 `enabled = false` / 连接失败降级）。补齐配置后重启 worker；启动日志可见「对象存储已就绪」或「storage 连接失败」告警 |
|
||||
| 容器内 import `workers.demo` 失败 | 确认在容器工作目录（zip 根）启动，`start.sh` 内含 `cd "$(dirname "$0")"`，worker_serve 会把 CWD 加入 sys.path |
|
||||
|
||||
---
|
||||
|
||||
## 8. 相关命令速查
|
||||
## 9. 相关命令速查
|
||||
|
||||
```bash
|
||||
uv run worker_serve --type <name> # 本地调试独立 Worker 进程
|
||||
@@ -373,7 +458,7 @@ uv run python test_process_mode_e2e.py # 端到端测试（先启动网
|
||||
|
||||
---
|
||||
|
||||
## 9. 参考
|
||||
## 10. 参考
|
||||
|
||||
- [主 README：进程插件与混合部署](../README.md)
|
||||
- [Worker 插件开发指南（inline，结构约定与装饰器细节）](../src/plugins/README.md)
|
||||
|
||||
Reference in New Issue
Block a user