存储配置

FileCodeBox 支持多种存储后端，您可以根据需求选择合适的存储方式。本文档将详细介绍各种存储后端的配置方法。

存储类型概览

存储类型	配置值	说明
本地存储	`local`	默认存储方式，文件保存在服务器本地
S3 兼容存储	`s3`	支持 AWS S3、阿里云 OSS、MinIO 等
OneDrive	`onedrive`	微软 OneDrive 云存储（仅支持工作/学校账户）
WebDAV	`webdav`	支持 WebDAV 协议的存储服务
OpenDAL	`opendal`	通过 OpenDAL 集成更多存储服务

本地存储

本地存储是默认的存储方式，文件将保存在服务器的 data/ 目录下。

配置参数

参数	类型	默认值	说明
`file_storage`	string	`local`	存储类型
`storage_path`	string	`""`	自定义存储路径（可选）

配置示例

bash

file_storage=local
storage_path=

说明

文件默认存储在 data/share/data/ 目录下
按日期自动创建子目录：年/月/日/文件ID/
建议在生产环境中将 data/ 目录挂载到持久化存储

S3 兼容存储

支持所有 S3 兼容的对象存储服务，包括 AWS S3、阿里云 OSS、MinIO、腾讯云 COS 等。

配置参数

参数	类型	默认值	说明
`file_storage`	string	-	设置为 `s3`
`s3_access_key_id`	string	`""`	Access Key ID
`s3_secret_access_key`	string	`""`	Secret Access Key
`s3_bucket_name`	string	`""`	存储桶名称
`s3_endpoint_url`	string	`""`	S3 端点 URL
`s3_region_name`	string	`auto`	区域名称
`s3_signature_version`	string	`s3v2`	签名版本（`s3v2` 或 `s3v4`）
`s3_hostname`	string	`""`	S3 主机名（备用）
`s3_proxy`	int	`0`	是否通过服务器代理下载（1=是，0=否）
`aws_session_token`	string	`""`	AWS 会话令牌（可选）

AWS S3 配置示例

bash

file_storage=s3
s3_access_key_id=AKIAIOSFODNN7EXAMPLE
s3_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
s3_bucket_name=my-filecodebox-bucket
s3_endpoint_url=https://s3.amazonaws.com
s3_region_name=us-east-1
s3_signature_version=s3v4

阿里云 OSS 配置示例

bash

file_storage=s3
s3_access_key_id=您的AccessKeyId
s3_secret_access_key=您的SecretAccessKey
s3_bucket_name=bucket-name
s3_endpoint_url=https://bucket-name.oss-cn-hangzhou.aliyuncs.com
s3_region_name=oss-cn-hangzhou
s3_signature_version=s3v4

阿里云 OSS 端点格式

端点 URL 格式为：https://<bucket-name>.<region>.aliyuncs.com

常用区域：

杭州：oss-cn-hangzhou
上海：oss-cn-shanghai
北京：oss-cn-beijing
深圳：oss-cn-shenzhen

MinIO 配置示例

bash

file_storage=s3
s3_access_key_id=minioadmin
s3_secret_access_key=minioadmin
s3_bucket_name=filecodebox
s3_endpoint_url=http://localhost:9000
s3_region_name=us-east-1
s3_signature_version=s3v4

MinIO 注意事项

s3_endpoint_url 填写 MinIO 的 API 接口地址
s3_region_name 根据 MinIO 配置中的 Server Location 设置
确保存储桶已创建且有正确的访问权限

腾讯云 COS 配置示例

bash

file_storage=s3
s3_access_key_id=您的SecretId
s3_secret_access_key=您的SecretKey
s3_bucket_name=bucket-name-1250000000
s3_endpoint_url=https://cos.ap-guangzhou.myqcloud.com
s3_region_name=ap-guangzhou
s3_signature_version=s3v4

代理下载

当 s3_proxy=1 时，文件下载将通过服务器中转，而不是直接从 S3 下载。这在以下情况下有用：

S3 存储桶不允许公开访问
需要隐藏实际的存储地址
网络环境限制直接访问 S3

OneDrive 存储

OneDrive 存储支持将文件保存到微软 OneDrive 云存储。

重要限制

OneDrive 存储仅支持工作或学校账户，并且需要有管理员权限以授权 API。个人账户无法使用此功能。

配置参数

参数	类型	默认值	说明
`file_storage`	string	-	设置为 `onedrive`
`onedrive_domain`	string	`""`	Azure AD 域名
`onedrive_client_id`	string	`""`	应用程序（客户端）ID
`onedrive_username`	string	`""`	账户邮箱
`onedrive_password`	string	`""`	账户密码
`onedrive_root_path`	string	`filebox_storage`	OneDrive 中的存储根目录
`onedrive_proxy`	int	`0`	是否通过服务器代理下载

配置示例

bash

file_storage=onedrive
onedrive_domain=contoso.onmicrosoft.com
onedrive_client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
onedrive_username=[email protected]
onedrive_password=your_password
onedrive_root_path=filebox_storage

Azure 应用注册步骤

要使用 OneDrive 存储，您需要在 Azure 门户中注册应用程序：

1. 获取域名

2. 注册应用

点击左上角的 + 新注册
输入应用名称（如：FileCodeBox）
受支持的帐户类型：选择"任何组织目录(任何 Azure AD 目录 - 多租户)中的帐户和个人 Microsoft 帐户"
重定向 URI：选择 Web，输入 http://localhost
点击注册

3. 获取客户端 ID

注册完成后，在应用概述页面的概要中找到应用程序(客户端)ID，即为 onedrive_client_id 的值。

4. 配置身份验证

在左侧菜单选择身份验证
找到允许公共客户端流，选择是
点击保存

5. 配置 API 权限

在左侧菜单选择 API 权限
点击 + 添加权限
选择 Microsoft Graph → 委托的权限
勾选以下权限：
- openid
- Files.Read
- Files.Read.All
- Files.ReadWrite
- Files.ReadWrite.All
- User.Read
点击添加权限
点击代表 xxx 授予管理员同意
确认后，权限状态应显示为已授予

安装依赖

使用 OneDrive 存储需要安装额外的 Python 依赖：

bash

pip install msal Office365-REST-Python-Client

验证配置

您可以使用以下代码测试配置是否正确：

python

import msal
from office365.graph_client import GraphClient

domain = 'your_domain'
client_id = 'your_client_id'
username = 'your_username'
password = 'your_password'

def acquire_token_pwd():
    authority_url = f'https://login.microsoftonline.com/{domain}'
    app = msal.PublicClientApplication(
        authority=authority_url,
        client_id=client_id
    )
    result = app.acquire_token_by_username_password(
        username=username,
        password=password,
        scopes=['https://graph.microsoft.com/.default']
    )
    return result

# 测试连接
client = GraphClient(acquire_token_pwd)
me = client.me.get().execute_query()
print(f"登录成功：{me.user_principal_name}")

WebDAV 存储

WebDAV 存储支持将文件保存到任何支持 WebDAV 协议的服务，如 Nextcloud、ownCloud、坚果云等。

配置参数

参数	类型	默认值	说明
`file_storage`	string	-	设置为 `webdav`
`webdav_url`	string	`""`	WebDAV 服务器 URL
`webdav_username`	string	`""`	WebDAV 用户名
`webdav_password`	string	`""`	WebDAV 密码
`webdav_root_path`	string	`filebox_storage`	WebDAV 中的存储根目录
`webdav_proxy`	int	`0`	是否通过服务器代理下载

配置示例

bash

file_storage=webdav
webdav_url=https://dav.example.com/remote.php/dav/files/username/
webdav_username=your_username
webdav_password=your_password
webdav_root_path=filebox_storage

Nextcloud 配置示例

bash

file_storage=webdav
webdav_url=https://your-nextcloud.com/remote.php/dav/files/username/
webdav_username=your_username
webdav_password=your_app_password
webdav_root_path=FileCodeBox

Nextcloud 应用密码

建议在 Nextcloud 中创建应用密码，而不是使用主密码：

登录 Nextcloud
进入设置 → 安全
在设备与会话中创建新的应用密码

坚果云配置示例

bash

file_storage=webdav
webdav_url=https://dav.jianguoyun.com/dav/
webdav_username=[email protected]
webdav_password=your_app_password
webdav_root_path=FileCodeBox

坚果云应用密码

坚果云需要使用应用密码：

登录坚果云网页版
进入账户信息 → 安全选项
添加应用密码

OpenDAL 存储

OpenDAL 是一个统一的数据访问层，支持多种存储服务。通过 OpenDAL，您可以使用 Google Cloud Storage、Azure Blob Storage 等更多存储服务。

配置参数

参数	类型	说明
`file_storage`	string	设置为 `opendal`
`opendal_scheme`	string	存储服务类型（如 `gcs`、`azblob`）
`opendal_<scheme>_<setting>`	string	服务特定的配置参数

安装依赖

bash

pip install opendal

Google Cloud Storage 配置示例

bash

file_storage=opendal
opendal_scheme=gcs
opendal_gcs_root=/filecodebox
opendal_gcs_bucket=your-bucket-name
opendal_gcs_credential=base64_encoded_credential

Azure Blob Storage 配置示例

bash

file_storage=opendal
opendal_scheme=azblob
opendal_azblob_root=/filecodebox
opendal_azblob_container=your-container
opendal_azblob_account_name=your_account
opendal_azblob_account_key=your_key

支持的服务

OpenDAL 支持众多存储服务，完整列表请参考 OpenDAL 官方文档。

常用服务包括：

gcs - Google Cloud Storage
azblob - Azure Blob Storage
obs - 华为云 OBS
oss - 阿里云 OSS（通过 OpenDAL）
cos - 腾讯云 COS（通过 OpenDAL）
hdfs - Hadoop HDFS
ftp - FTP 服务器
sftp - SFTP 服务器

OpenDAL 注意事项

通过 OpenDAL 集成的服务均通过服务器中转下载，会同时消耗存储服务和服务器的流量
相比原生 S3/OneDrive 支持，OpenDAL 方式可能缺少一些调试信息
OpenDAL 采用 Rust 编写，性能较好

存储选择建议

场景	推荐存储	原因
个人/小型部署	本地存储	简单易用，无需额外配置
企业内网	MinIO + S3	自建对象存储，数据可控
公有云部署	对应云厂商 S3	同区域访问快，成本低
已有 OneDrive	OneDrive	利用现有资源
已有 WebDAV	WebDAV	兼容性好
特殊存储需求	OpenDAL	支持更多存储服务

常见问题

S3 上传失败

检查 Access Key 和 Secret Key 是否正确
确认存储桶名称和区域配置正确
检查存储桶的访问权限设置
确认签名版本（s3v2 或 s3v4）与服务商要求一致

OneDrive 认证失败

确认使用的是工作/学校账户，而非个人账户
检查 Azure 应用是否已授予管理员同意
确认 API 权限配置完整
验证用户名和密码是否正确

WebDAV 连接失败

检查 WebDAV URL 格式是否正确
确认用户名和密码（或应用密码）正确
检查服务器是否支持 WebDAV 协议
确认网络连接正常

存储配置 ​

存储类型概览 ​

本地存储 ​

配置参数 ​

配置示例 ​

说明 ​

S3 兼容存储 ​

配置参数 ​

AWS S3 配置示例 ​

阿里云 OSS 配置示例 ​

MinIO 配置示例 ​

腾讯云 COS 配置示例 ​

代理下载 ​

OneDrive 存储 ​

配置参数 ​

配置示例 ​

Azure 应用注册步骤 ​

1. 获取域名 ​

2. 注册应用 ​

3. 获取客户端 ID ​

4. 配置身份验证 ​

5. 配置 API 权限 ​

安装依赖 ​

验证配置 ​

WebDAV 存储 ​

配置参数 ​

配置示例 ​

Nextcloud 配置示例 ​

坚果云配置示例 ​

OpenDAL 存储 ​

配置参数 ​

安装依赖 ​

Google Cloud Storage 配置示例 ​

Azure Blob Storage 配置示例 ​

支持的服务 ​

存储选择建议 ​

常见问题 ​

S3 上传失败 ​

OneDrive 认证失败 ​

WebDAV 连接失败 ​

存储配置

存储类型概览

本地存储

配置参数

配置示例

说明

S3 兼容存储

配置参数

AWS S3 配置示例

阿里云 OSS 配置示例

MinIO 配置示例

腾讯云 COS 配置示例

代理下载

OneDrive 存储

配置参数

配置示例

Azure 应用注册步骤

1. 获取域名

2. 注册应用

3. 获取客户端 ID

4. 配置身份验证

5. 配置 API 权限

安装依赖

验证配置

WebDAV 存储

配置参数

配置示例

Nextcloud 配置示例

坚果云配置示例

OpenDAL 存储

配置参数

安装依赖

Google Cloud Storage 配置示例

Azure Blob Storage 配置示例

支持的服务

存储选择建议

常见问题

S3 上传失败

OneDrive 认证失败

WebDAV 连接失败