# WebDAV / S3 云存储配置

在配置云同步时，你可以选择将同步数据存放在自己持有的第三方云存储中（例如自建的 WebDAV 服务，或是各平台提供的 S3 兼容对象存储），从而实现对数据存储位置和合规的完全自主掌控。

在此模式下，剪贴内容在到达存储前会**用你持有的密钥在设备本地完成端到端加密**，云端存储桶只保存加密后的密文。章鱼速贴的服务器不会拿到你的存储凭据、加密密钥或剪贴内容。存储桶的可用性、数据保留和安全完全由你自己负责。

## 支持方式概览

| 方式        | 典型实现                                  | 适用场景               |
| ----------- | ----------------------------------------- | ---------------------- |
| WebDAV      | 自建 WebDAV / 第三方网盘服务              | 快速接入、运维成本较低 |
| S3 兼容存储 | Amazon S3 / MinIO / 阿里云 OSS 等对象存储 | 规模化、权限策略细粒度 |

## 基础配置字段

| 字段         | 类型     |     必填      | 说明                                                                                                                                           |
| ------------ | -------- | :-----------: | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`   | `string` |      Yes      | 存储类型，如 `webdav`、`s3`                                                                                                                    |
| `endpoint`   | `string` |      Yes      | 服务地址                                                                                                                                       |
| `bucket`     | `string` |      No       | 对象存储桶名（S3 场景）                                                                                                                        |
| `username`   | `string` |      No       | 账号（WebDAV）或 Access Key ID（S3）                                                                                                           |
| `password`   | `string` |      No       | 密码（WebDAV）或 Secret Access Key（S3）                                                                                                       |
| `pathPrefix` | `string` |      No       | 同步路径前缀                                                                                                                                   |
| 加密密钥     | `string` | Yes（应用内） | 端到端加密密钥。你在**应用内设置中的「加密密钥」**处输入，它保存在设备钥匙串中，**不会写入本配置文件**。每台设备必须使用**相同**的值才能解密。 |

## 配置步骤

:::steps
:::step{title="选定并备份加密密钥"}

先确定你要使用的端到端加密密钥，并将其保存到密码管理器。你需要在每台设备上输入**完全一致**的密钥，否则对端设备无法解密你同步的内容。

:::
:::step{title="准备存储服务凭据"}

确认服务地址、账号和权限策略已就绪。S3 的访问密钥至少需要对目标桶具备 `s3:PutObject`、`s3:GetObject`、`s3:DeleteObject` 和 `s3:ListBucket` 等基本权限；WebDAV 可用 HEAD 请求确认地址能正常响应。

:::
:::step{title="在应用中填写存储参数"}

在章鱼速贴的云同步设置中，按实际服务类型填写各项参数并保存，同时填入本地加密密钥。

:::
:::step{title="执行连接测试"}

确认可以正常读写测试对象，再开启正式同步。**成功标志：** 界面提示「测试连接成功」或「连接成功」，此时即可开启同步。
:::
:::

## 示例配置

下面的示例仅包含存储字段——加密密钥仅在应用内部进行安全存储，不会以明文保存在此配置中。请将尖括号内的值替换为你自己的凭据（这些只是占位符，不是真实值）。

```json title="storage.config.json"
{
  "provider": "s3",
  "endpoint": "https://s3.example.com",
  "bucket": "octoclip-sync",
  "pathPrefix": "prod/user-a/",
  "username": "<your-access-key-id>",
  "password": "<your-secret-access-key>"
}
```

> [!DANGER] 凭据与密钥勿入公开仓库
> 请勿将包含凭据的配置文件提交到 GitHub 等公开仓库，更不要把端到端加密密钥粘贴到任何共享渠道；建议在应用设置中完成输入。

## 常见问题

:::accordion
:::item{label="连接测试失败怎么办？"}

请先检查 `endpoint` 服务地址是否可达、凭据有效性以及服务商侧桶/目录的读写权限策略。

:::
:::item{label="多设备数据冲突怎么处理？"}

云同步目标是保证多端数据的最终一致性。如果因网络同步延迟产生冲突，请以本地历史记录为准，必要时可通过重新复制或从本地备份中恢复。

:::
:::item{label="内容已到达却无法读取 / 不显示"}

请确保每台设备配置的**加密密钥完全一致**。如果密钥不一致，对端即使正常拉取到密文也无法解密显示，且不会主动报错。
:::
:::

## 相关文档

:::cards{cols=2}
:::card{title="云同步" icon="lucide.cloud" href="/features/cloud-sync"}
了解云同步机制与配置流程。

:::
:::card{title="隐私与安全" icon="lucide.shield" href="/advanced/privacy-security"}
查看凭据与敏感数据保护建议。
:::
:::