接口附件存储配置教程（七牛云/阿里云OSS）

网程聚合数据 2026-10-31 05:36 6 阅读新手教程

接口附件存储配置教程：在用户中心参数配置页选择七牛云或阿里云OSS并填写自己的凭证，文档转换等接口才能返回文件链接。含必填项与覆盖保存注意事项。

文档转换、签章、二维码、文件上传等接口会产出文件，这些文件需要存到**你自己的**云存储里，接口才能返回可下载的链接。平台不提供公共兜底存储，因此这类接口在使用前必须先配置存储凭证。

配置入口在用户中心「开发者中心」→「参数配置」页的「接口附件配置」选项卡，地址 `/member/developer/attach-config`，支持七牛云存储与阿里云 OSS 两种后端。

## 一、配置说明

- **凭证维度**：用户级。每个账号保存自己的一份配置，只影响自己的调用，与其他用户无关。
- **二选一**：「远程附件」下拉只能选「七牛云存储」或「阿里云OSS」其中一个，接口产物只会上传到选中的那一个后端。
- **必须先配置**：未配置或必填项缺失时，相关接口会直接返回错误，提示「请先在 用户中心→开发者中心→参数配置→接口附件配置 中配置存储凭证」，**不会退回本站临时链接**。
- **涉及的接口**：文件上传、PDF 转文档、文档转 PDF、文档转图片、图片转 PNG、Markdown 转 docx、签章生成与提取、文档自动签章、二维码生成、图片方向矫正、文档翻译等。此外，任何接口在你传 `file_base64` 而上游只接受 URL 时，也会先把文件上传到你的存储换取公网链接。
- **保存即生效**：这份配置每次读取都直连数据库，没有缓存延迟，保存成功后下一次调用就按新配置走。
- **文件在云端的路径**：`{存储目录}/uploads/{类别}/{日期}/{文件名}`，返回的链接是**无签名的直链**，因此存储空间需要允许公共读，否则你和上游都取不到文件。
- **产物不在平台本地留存**：上传成功后本地副本即删除；上传失败时才会保留本地文件兜底。

## 二、在云存储侧准备

**七牛云**：创建一个存储空间（Bucket），记下空间名称、AccessKey 与 SecretKey，并为空间绑定一个可公网访问的**附件域名**。空间需为公共读，或至少保证生成的直链能被外部下载。七牛的存储区域由 SDK 自动处理，页面上不需要填区域。

**阿里云 OSS**：创建一个 Bucket，记下 Bucket 名称、AccessKey、SecretKey 与所在地域的 **Endpoint**（形如 `oss-cn-beijing.aliyuncs.com`）。用于调用的 AccessKey 需要有该 Bucket 的写入与删除权限。若希望链接用自己的域名，再准备一个已绑定到该 Bucket 的外网域名；不填则平台按 `https://{Bucket}.{Endpoint}/...` 拼出链接。

> 两边的 AccessKey 都建议使用最小权限的子账号密钥（七牛用子账号、OSS 用 RAM 用户），只授予目标空间的读写权限，不要用主账号密钥。

> 备案与域名要求以云服务商当时的规则为准，平台侧只要求你填的域名能公网访问。

## 三、在用户中心填写并保存

**第 1 步：进入配置页。** 登录 <https://www.phpwc.cn/member/login> 后，访问 <https://www.phpwc.cn/member/developer/attach-config>，或点击左侧菜单「开发者中心」→「参数配置」，停在「接口附件配置」选项卡。

**第 2 步：选择远程附件后端。** 在「远程附件」下拉里选「七牛云存储」或「阿里云OSS」。页面上两张凭证卡片始终同时显示，**只需填写你选中的那一张**，另一张留空即可。

**第 3 步：填写对应凭证。**

七牛云存储：

| 字段 | 是否必填 | 填写说明 |
|---|---|---|
| AccessKey | 必填 | 七牛密钥管理里的 AccessKey |
| SecretKey | 必填 | 与 AccessKey 配对的 SecretKey |
| 空间名称 | 必填 | 存储空间（Bucket）名称 |
| 存储目录 | 选填 | 文件存放的前缀目录，如 `/` 或 `uploads`，留空即放在根目录 |
| 附件域名 | 必填 | 空间绑定的访问域名，如 `http://cdn.example.com`；不带协议时平台会自动补 `https://` |

阿里云OSS：

| 字段 | 是否必填 | 填写说明 |
|---|---|---|
| AccessKey | 必填 | 阿里云 AccessKey ID |
| SecretKey | 必填 | 对应的 AccessKey Secret |
| 空间名称（Bucket） | 必填 | OSS Bucket 名称 |
| Endpoint | 必填 | 地域节点，如 `oss-cn-beijing.aliyuncs.com`，不要带 `https://` 与 Bucket 前缀 |
| 存储目录 | 选填 | 同上，留空即根目录 |
| 外网域名 | 选填 | 绑定到该 Bucket 的自定义域名；留空则用 `Bucket.Endpoint` 默认域名 |

**第 4 步：点击「保存配置」。** 成功提示「保存成功」（约 3 秒后消失）。未选后端会提示「请选择远程附件存储后端」，必填项缺失会提示「请填写 字段名」，按提示补齐即可。本页没有「测试连接」按钮，也没有删除或清空配置的按钮。

> **重要：保存是整组覆盖式的。** 两套凭证会随表单一起提交，切换后端时如果你把原来那一套的输入框清空了，原来的凭证也会被一并写空。想保留备用配置，切换时不要删掉另一张卡片里已有的内容。

> 凭证在本页是明文回显、明文保存的，页面上没有打码。请妥善保管账号登录信息，截图分享时注意遮挡；怀疑泄露时先到云服务商侧禁用或轮换密钥，再回到本页覆盖保存新值。

**相关操作**：左侧菜单「任务与附件」→「API附件管理」（`/member/api-attachment`）提供「清空云存储附件」按钮，用于批量删除已上传到你云空间的远程文件（只删云端文件，不删台账记录）；未配置存储时点击会提示「未配置云存储后端」。异步任务的产物状态与下载地址在「异步任务列表」查看。

**文件大小限制**（文件上传接口的内置上限）：图像 10MB、文档 50MB、音频 50MB、视频 100MB、其他类型 20MB，超限会提示「{类别} 文件大小超过限制，最大允许 {N}MB」。允许的扩展名以接口文档页的参数说明为准。

常见问题

Q：为什么一定要配置自己的存储，不配会怎样？

A：文档转换、签章、二维码、文件上传等接口会产出文件，平台不提供公共兜底存储，这些文件必须存到你自己的七牛云或阿里云OSS 空间里才能返回下载链接。未配置或必填项缺失时，相关接口会直接返回错误并提示先到用户中心开发者中心的参数配置页配置存储凭证，不会退回本站临时链接。这份配置是用户级的，只影响你自己的调用。

Q：七牛云和阿里云OSS 可以同时启用吗？哪些字段必须填？

A：不能同时启用，远程附件下拉只能二选一，接口产物只上传到选中的那一个后端。七牛必填 AccessKey、SecretKey、空间名称、附件域名，存储目录选填；阿里云OSS 必填 AccessKey、SecretKey、空间名称（Bucket）、Endpoint，存储目录与外网域名选填。页面上两张卡片始终同时显示，只需填写你选中的那一张，另一张留空即可。

Q：切换存储后端时要注意什么？保存后多久生效？

A：保存是整组覆盖式的，两套凭证会随表单一起提交。切换后端时如果把原来那一套的输入框清空了，原凭证也会被一并写空，想保留备用配置就不要删掉另一张卡片里已有的内容。保存成功后提示保存成功，这份配置每次读取都直连数据库，没有缓存延迟，下一次调用就按新配置走。本页没有测试连接按钮，也没有删除配置的按钮。

新手教程用户中心附件存储七牛云阿里云OSS

上一篇：点数充值与扣费规则教程下一篇：VIP 套餐购买与权益说明教程

网友评论（0）

暂无评论，快来抢沙发～