内容
# 上传服务
基于Cloudflare Workers的轻量级文件托管后端，构建在 [files-sdk](https://files-sdk.dev) 之上，因此存储层是与提供商无关的（目前为R2；未来可使用任何files-sdk适配器）。继`buildinternet-skills/github-screenshots`中的R2上传脚本之后。
> **正在积极开发中 — 未达到生产就绪状态。** uploads.sh正在公开开发中，其API（包括身份验证）将可能会在没有通知的情况下更改。请勿依赖它处理任何您无法承受损失或重新密钥的数据。
## 快速开始
```bash
pnpm install
cp apps/api/.dev.vars.example apps/api/.dev.vars
pnpm workspace:add default --local
pnpm dev # API在 :8787; pnpm dev:web 用于网站
```
上传文件：
```bash
curl -X PUT http://localhost:8787/v1/default/files/test.txt \
-H "Authorization: Bearer $UPLOADS_TOKEN" \
-H "Content-Type: text/plain" \
--data-binary "hello"
```
### 命令行界面
`@buildinternet/uploads` 包为脚本和GitHub图像嵌入提供了API封装。`pnpm workspace:add` 会一次性打印出Bearer令牌 — 将其保存到 `.env`（来自 `.env.example`）或运行 `pnpm uploads setup --token <token>`。
```bash
cp .env.example .env # 从 workspace:add 输出中填写 UPLOADS_TOKEN
pnpm uploads put ./shot.png --env-file .env
# 标准输出：公共URL + 可粘贴的Markdown；标准错误：人类总结
```
**密钥工作原理：** 默认 `put` 是快速通道 — 运行它时不带任何标志，你会得到一个唯一的公共URL（`screenshots/<repo>/<date>/<name>-<hash>.<ext>`）。在需要GitHub嵌入的稳定、无哈希文件名时使用 `--pr` 或 `--issue`。仅在需要确切路径时使用 `--key`。
更多输出控制：
```bash
pnpm uploads put ./shot.png --format url --env-file .env
pnpm uploads put ./shot.png --repo myorg/myapp --ref 1722 --width 700 --env-file .env
```
### GitHub 嵌入
GitHub的原生图像托管仅通过浏览器会话有效 — 代理和 `gh` 需要一个公共URL。首先，命令行界面上传到R2并返回一个稳定的Markdown，您可以将其放入PR或问题中。
**稳定的PR/问题附件**（ `--pr` / `--issue` ）使用无哈希密钥，因此重新上传相同文件名会覆盖原始文件，URL永远不会更改：
```bash
pnpm uploads put ./after.png --pr 123 --alt "Dashboard after" --env-file .env
# 密钥： gh/<owner>/<repo>/pull/123/after.png
```
**托管附件评论**（ `--comment` ，需要本地 `gh` 身份验证）创建或更新一个评论，列出附加到该PR/问题的所有文件 — 如果 `gh` 不可用，上传仍然成功：
```bash
pnpm uploads put ./after.png --pr 123 --comment --env-file .env
pnpm uploads comment --pr 123 --env-file .env # 重新同步，无需上传
```
> **隐私：**托管文件从公共CDN提供服务，与GitHub仓库可见性无关。私有PR上的屏幕截图仍然可以通过任何知道或猜测到URL的人访问 — `--pr`/`--issue` 密钥嵌入了仓库路径和文件名（`gh/myorg/myapp/pull/123/after.png`），因此通用名称比哈希密钥更容易猜测。请将上传视为公开的；不要托管秘密或敏感UI。计划为私有仓库提供更严格的访问控制 — 参见 [路线图](docs/roadmap.md)。
参见 `skills/uploads-cli/SKILL.md` 以了解面向代理的用法和 [docs/api.md](docs/api.md) 以了解REST路由。
## 布局
```
apps/api Hono worker — REST API，部署到 api.uploads.sh
apps/web Astro placeholder — 未来的浏览/管理UI
packages/storage @uploads/storage — files-sdk适配器工厂
packages/uploads @buildinternet/uploads — CLI + GitHub图像嵌入客户端
skills/uploads-cli 驱动CLI的代理技能
```
API和Web应用程序是单独部署的。所有存储访问都通过 `packages/storage` 中的 `createStorage()` 进行 — 添加提供程序只需要一个新案例和对等依赖项，无需更改API。
## 文档
| 文档 | 内容 |
| ------------------------------------ | -------------------------------------------- |
| [工作区](docs/workspaces.md) | 多租户模型，注册，BYO-bucket |
| [管理员令牌](docs/admin-tokens.md) | 铸造，列出和撤销上传令牌 |
| [API](docs/api.md) | REST路由和CLI用法 |
| [部署](docs/deploy.md) | Cloudflare设置和生产部署 |
| [路线图](docs/roadmap.md) | 计划功能 |
代理和贡献者约定位于 [AGENTS.md](AGENTS.md)。
MCP 市场