FileCodeBox 存储后端配置指南本地磁盘、S3、OneDrive、WebDAV 与 OpenDAL 的完整切换实战【免费下载链接】FileCodeBox文件快递柜-匿名口令分享文本文件像拿快递一样取文件FileCodeBox - File Express Cabinet - Anonymous Passcode Sharing Text, Files, Like Taking Express Delivery for Files项目地址: https://gitcode.com/GitHub_Trending/fi/FileCodeBoxFileCodeBox文件快递柜通过统一的存储抽象层将文件保存与文件分享业务解耦原生支持本地磁盘、S3 兼容对象存储、Microsoft OneDrive、WebDAV 以及基于 OpenDAL 的多种云存储。本文以官方存储配置文档为主体结合仓库源码与测试用例系统讲解五种存储后端的参数含义、配置示例、底层实现原理与常见排障方法。读完本文你将能够根据部署场景选择正确的存储后端并完成从本地存储到对象存储 / 云盘的平滑切换。存储架构一个接口五种后端在深入配置之前先了解 FileCodeBox 的存储架构。所有后端都实现同一个抽象基类FileStorageInterface定义于 core/storage.py核心方法包括方法职责save_file保存二进制流上传入口delete_file按StoredFile删除文件get_file_url获取可分享的下载 URLget_file_response获取文件下载响应服务器中转模式save_chunk/merge_chunks/clean_chunks分片上传的三段式生命周期generate_presigned_upload_url生成预签名直传 URL默认返回None即不支持直传时走代理模式file_exists校验文件是否已存在文件模块底部通过一个字典注册了全部实现core/storage.pystorages { local: SystemFileStorage, s3: S3FileStorage, onedrive: OneDriveFileStorage, opendal: OpenDALFileStorage, webdav: WebDAVFileStorage, }业务层如 apps/base/views.py 的下载接口通过storages[settings.file_storage]()动态实例化后端因此切换存储只需修改file_storage配置项业务代码完全无感。存储层刻意保持与 ORM 无关StoredFile与StoredDownload两个 dataclasscore/storage.py只承载纯数据由视图层负责构建响应保证core/不反向依赖apps/。所有存储相关配置的默认值集中定义在 core/settings.py 的DEFAULT_CONFIG中首次启动生效修改后持久化到data/filecodebox.db数据库。配置方式详见 docs/guide/configuration.md。存储类型概览存储类型配置值说明本地存储local默认存储方式文件保存在服务器本地S3 兼容存储s3支持 AWS S3、阿里云 OSS、MinIO 等OneDriveonedrive微软 OneDrive 云存储仅支持工作/学校账户WebDAVwebdav支持 WebDAV 协议的存储服务OpenDALopendal通过 OpenDAL 集成更多存储服务本地存储本地存储是默认的存储方式文件保存在服务器的data/目录下对应源码实现SystemFileStoragecore/storage.py。配置参数参数类型默认值说明file_storagestringlocal存储类型storage_pathstring自定义存储路径可选配置示例file_storagelocal storage_path目录结构与实现要点文件默认存储在data/share/data/目录下按日期自动创建子目录年/月/日/文件ID/建议在生产环境中将data/目录挂载到持久化存储Docker 部署时 docker-compose.yml 已通过fcb-data:/app/data:rw卷声明持久化从源码看本地后端还有几个值得注意的安全与可靠性设计路径穿越防护_resolve_safe_pathcore/storage.py将所有相对路径解析到数据根目录内拒绝含..的路径并校验解析结果必须位于根目录之下。测试 tests/test_security_hardening.py 专门验证了../etc/passwd这类攻击路径会被拦截。流式写入save_file通过asyncio.to_thread将同步文件写入调度到线程池避免阻塞事件循环core/storage.py。分片合并的原子性分片先写入带.tmp后缀的临时文件校验通过后原子重命名合并时使用.merging后缀临时文件任一环节失败即清理保证磁盘上不会出现半成品文件core/storage.py。测试 tests/test_merge_chunks.py 完整覆盖了分片合并、哈希校验与清理流程。分片校验每个分片写入时携带 SHA-256 哈希合并时逐片比对同时累计出整文件哈希_verify_and_hash_chunkcore/storage.py确保大文件上传的完整性。S3 兼容存储S3 后端S3FileStoragecore/storage.py支持所有 S3 兼容的对象存储服务包括 AWS S3、阿里云 OSS、MinIO、腾讯云 COS 等。其底层基于aioboto3异步客户端实现支持流式上传upload_fileobj避免整文件载入内存与分片 multipart 合并。配置参数参数类型默认值说明file_storagestring-设置为s3s3_access_key_idstringAccess Key IDs3_secret_access_keystringSecret Access Keys3_bucket_namestring存储桶名称s3_endpoint_urlstringS3 端点 URLs3_region_namestringauto区域名称s3_signature_versionstrings3v2签名版本s3v2或s3v4s3_hostnamestringS3 主机名备用未设置s3_endpoint_url时自动拼为https://{hostname}s3_proxyint0是否通过服务器代理下载1是0否aws_session_tokenstringAWS 会话令牌可选源码中还有两个文档之外的实用参数s3_addressing_style默认auto可设为path或virtual用于控制桶寻址风格测试 tests/test_issue_461_s3_addressing.py 验证了path风格的客户端配置生成。s3_hostname在s3_endpoint_url为空时充当备用端点core/storage.py。AWS S3 配置示例file_storages3 s3_access_key_idAKIAIOSFODNN7EXAMPLE s3_secret_access_keywJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY s3_bucket_namemy-filecodebox-bucket s3_endpoint_urlhttps://s3.amazonaws.com s3_region_nameus-east-1 s3_signature_versions3v4阿里云 OSS 配置示例file_storages3 s3_access_key_id您的AccessKeyId s3_secret_access_key您的SecretAccessKey s3_bucket_namebucket-name s3_endpoint_urlhttps://bucket-name.oss-cn-hangzhou.aliyuncs.com s3_region_nameoss-cn-hangzhou s3_signature_versions3v4阿里云 OSS 端点格式端点 URL 格式为https://bucket-name.region.aliyuncs.com常用区域杭州oss-cn-hangzhou、上海oss-cn-shanghai、北京oss-cn-beijing、深圳oss-cn-shenzhenMinIO 配置示例file_storages3 s3_access_key_idminioadmin s3_secret_access_keyminioadmin s3_bucket_namefilecodebox s3_endpoint_urlhttp://localhost:9000 s3_region_nameus-east-1 s3_signature_versions3v4MinIO 注意事项s3_endpoint_url填写 MinIO 的 API 接口地址s3_region_name根据 MinIO 配置中的Server Location设置确保存储桶已创建且有正确的访问权限腾讯云 COS 配置示例file_storages3 s3_access_key_id您的SecretId s3_secret_access_key您的SecretKey s3_bucket_namebucket-name-1250000000 s3_endpoint_urlhttps://cos.ap-guangzhou.myqcloud.com s3_region_nameap-guangzhou s3_signature_versions3v4代理下载与直连模式当s3_proxy1时文件下载将通过服务器中转而不是直接从 S3 下载。这在以下场景下有用S3 存储桶不允许公开访问需要隐藏实际的存储地址网络环境限制直接访问 S3源码实现印证了这两种模式的分工core/storage.pys3_proxy0时get_file_url返回有效期 1 小时的预签名get_objectURL 供浏览器直连s3_proxy1时则调用get_file_url(code)生成服务器中转地址下载响应通过get_file_response的流式生成器64KB 分块经服务器转发。即使采用直连模式get_file_response也会先head_object探测Content-Length尽可能为下载提供准确的响应头core/storage.py。此外S3 后端实现了generate_presigned_upload_url默认 15 分钟有效期可自定义expires_in支持浏览器直传对象存储以绕开服务器带宽详见 docs/api/presign-upload.md。file_exists内置 3 次重试 退避0.2s 起逐次递增并在 HEAD 失败后回退到list_objects_v2精确比对测试 tests/test_issue_478_s3_file_exists.py 覆盖了命中与未命中两条路径。OneDrive 存储OneDrive 后端OneDriveFileStoragecore/storage.py将文件保存到微软 OneDrive 云存储基于msalMicrosoft 身份库与Office365-REST-Python-Client实现 Graph API 调用。重要限制OneDrive 存储仅支持工作或学校账户并且需要有管理员权限以授权 API。个人账户无法使用此功能。配置参数参数类型默认值说明file_storagestring-设置为onedriveonedrive_domainstringAzure AD 域名onedrive_client_idstring应用程序客户端IDonedrive_usernamestring账户邮箱onedrive_passwordstring账户密码onedrive_root_pathstringfilebox_storageOneDrive 中的存储根目录onedrive_proxyint0是否通过服务器代理下载配置示例file_storageonedrive onedrive_domaincontoso.onmicrosoft.com onedrive_client_idxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx onedrive_usernameusercontoso.onmicrosoft.com onedrive_passwordyour_password onedrive_root_pathfilebox_storageAzure 应用注册步骤使用 OneDrive 存储前需要在 Azure 门户中完成应用注册下述操作均在 Azure 门户的应用注册App registrations页面完成1. 获取域名登录 Azure 门户并进入应用注册列表页将鼠标置于右上角账号处浮窗显示的域即为onedrive_domain的值。2. 注册应用点击左上角的 新注册输入应用名称如FileCodeBox受支持的帐户类型选择任何组织目录(任何 Azure AD 目录 - 多租户)中的帐户和个人 Microsoft 帐户重定向 URI选择Web输入http://localhost点击注册3. 获取客户端 ID注册完成后在应用概述页面的概要中找到应用程序(客户端)ID即为onedrive_client_id的值。4. 配置身份验证在左侧菜单选择身份验证找到允许公共客户端流选择是点击保存5. 配置 API 权限在左侧菜单选择API 权限点击 添加权限选择Microsoft Graph→委托的权限勾选以下权限openidFiles.ReadFiles.Read.AllFiles.ReadWriteFiles.ReadWrite.AllUser.Read点击添加权限点击代表 xxx 授予管理员同意确认后权限状态应显示为已授予安装依赖使用 OneDrive 存储需要安装额外的 Python 依赖pip install msal Office365-REST-Python-Client未安装时OneDriveFileStorage.__init__会抛出明确的ImportError提示core/storage.py。验证配置您可以使用以下代码测试配置是否正确与源码中acquire_token_pwd的取号逻辑一致core/storage.pyimport 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 fhttps://login.microsoftonline.com/{domain} app msal.PublicClientApplication( authorityauthority_url, client_idclient_id ) result app.acquire_token_by_username_password( usernameusername, passwordpassword, 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})实现要点从源码可以进一步了解 OneDrive 后端的行为初始化时即验证凭据若根目录onedrive_root_path不存在会自动创建捕获itemNotFound后调用create_foldercore/storage.py保存文件时逐级创建目录结构core/storage.py非代理模式下通过 Graph API 创建 1 小时有效期的匿名分享链接并将 SharePoint 链接转换为download.aspx下载地址_convert_link_to_download_linkcore/storage.py。WebDAV 存储WebDAV 后端WebDAVFileStoragecore/storage.py将文件保存到任何支持 WebDAV 协议的服务如 Nextcloud、ownCloud、坚果云等。实现基于aiohttp通过标准 WebDAV 方法MKCOL建目录、PROPFIND列目录、PUT上传、DELETE删除与远端交互。配置参数参数类型默认值说明file_storagestring-设置为webdavwebdav_urlstringWebDAV 服务器 URLwebdav_usernamestringWebDAV 用户名webdav_passwordstringWebDAV 密码webdav_root_pathstringfilebox_storageWebDAV 中的存储根目录webdav_proxyint0是否通过服务器代理下载通用配置示例file_storagewebdav webdav_urlhttps://dav.example.com/remote.php/dav/files/username/ webdav_usernameyour_username webdav_passwordyour_password webdav_root_pathfilebox_storageNextcloud 配置示例file_storagewebdav webdav_urlhttps://your-nextcloud.com/remote.php/dav/files/username/ webdav_usernameyour_username webdav_passwordyour_app_password webdav_root_pathFileCodeBoxNextcloud 应用密码建议在 Nextcloud 中创建应用密码而不是使用主密码登录 Nextcloud进入设置→安全在设备与会话中创建新的应用密码坚果云配置示例file_storagewebdav webdav_urlhttps://dav.jianguoyun.com/dav/ webdav_usernameyour_emailexample.com webdav_passwordyour_app_password webdav_root_pathFileCodeBox坚果云应用密码坚果云需要使用应用密码登录坚果云网页版进入账户信息→安全选项添加应用密码实现要点WebDAV 后端同样实现了完整的目录自建逻辑_mkdir_p沿路径逐级 HEAD 探测、缺失则发MKCOL创建core/storage.py删除文件后还会通过PROPFIND判断空目录并递归清理_delete_empty_dirscore/storage.py避免远端残留空目录。上传采用 256KB 分块流式发送file_sender大文件不会整体载入内存分片合并借助本地临时文件中转规避内存峰值core/storage.py。OpenDAL 存储OpenDAL 是一个统一的数据访问层支持多种存储服务。通过 OpenDAL您可以使用 Google Cloud Storage、Azure Blob Storage 等更多存储服务。其实现OpenDALFileStoragecore/storage.py基于opendal.AsyncOperator异步操作符构造时会把所有opendal_scheme_*前缀的配置自动收集为对应服务的连接参数core/storage.py因此新增服务只需加配置、改opendal_scheme无需改动代码。配置参数参数类型说明file_storagestring设置为opendalopendal_schemestring存储服务类型如gcs、azblobopendal_scheme_settingstring服务特定的配置参数安装依赖pip install opendalGoogle Cloud Storage 配置示例file_storageopendal opendal_schemegcs opendal_gcs_root/filecodebox opendal_gcs_bucketyour-bucket-name opendal_gcs_credentialbase64_encoded_credentialAzure Blob Storage 配置示例file_storageopendal opendal_schemeazblob opendal_azblob_root/filecodebox opendal_azblob_containeryour-container opendal_azblob_account_nameyour_account opendal_azblob_account_keyyour_key支持的服务OpenDAL 支持众多存储服务完整列表以 OpenDAL 官方文档为准。常用服务包括gcs- Google Cloud Storageazblob- Azure Blob Storageobs- 华为云 OBSoss- 阿里云 OSS通过 OpenDALcos- 腾讯云 COS通过 OpenDALhdfs- Hadoop HDFSftp- FTP 服务器sftp- SFTP 服务器OpenDAL 注意事项通过 OpenDAL 集成的服务均通过服务器中转下载会同时消耗存储服务和服务器的流量相比原生 S3/OneDrive 支持OpenDAL 方式可能缺少一些调试信息OpenDAL 采用 Rust 编写性能较好存储选择建议场景推荐存储原因个人/小型部署本地存储简单易用无需额外配置企业内网MinIO S3自建对象存储数据可控公有云部署对应云厂商 S3同区域访问快成本低已有 OneDriveOneDrive利用现有资源已有 WebDAVWebDAV兼容性好特殊存储需求OpenDAL支持更多存储服务配套的storage_limit总存储配额字节0 表示不限制等配额参数定义于 core/settings.py其配额核算逻辑见 apps/base/quota.py相关测试见 tests/test_issue_486_storage_quota.py。常见问题S3 上传失败检查 Access Key 和 Secret Key 是否正确确认存储桶名称和区域配置正确检查存储桶的访问权限设置确认签名版本s3v2或s3v4与服务商要求一致国内对象存储服务通常要求s3v4若使用自定义端点确认s3_endpoint_url指向 API 地址而非控制台地址必要时检查s3_addressing_style是否为服务商要求的path或virtual风格OneDrive 认证失败确认使用的是工作/学校账户而非个人账户检查 Azure 应用是否已授予管理员同意确认 API 权限配置完整验证用户名和密码是否正确确认已安装msal与Office365-REST-Python-Client依赖core/storage.py 会给出缺失提示WebDAV 连接失败检查 WebDAV URL 格式是否正确注意协议为https://、路径以/结尾确认用户名和密码或应用密码正确检查服务器是否支持 WebDAV 协议确认网络连接正常切换后端的操作流程在管理面板/admin的存储设置中把file_storage改为目标值如s3并填写对应后端的全部参数或直接修改数据库data/filecodebox.db中的配置记录不推荐注意类型与安全配置保存后系统即时生效视图层每次请求都会通过storages[settings.file_storage]()重新实例化后端无需重启服务验证上传一个测试文件确认下载、删除、分片上传若启用三条链路均正常生产环境建议先在测试实例上完整走一遍 tests/test_integration_journey.py 覆盖的上传-提取-删除闭环后再切换。延伸阅读配置说明 - 全量配置项与配置组合示例含file_storage之外的配额、分片、上传限制等预签名上传 API - 基于 S3 预签名 URL 的浏览器直传方案存储层实现 - 五个后端的完整源码配置默认值定义 - 所有存储参数的默认值与类型约束【免费下载链接】FileCodeBox文件快递柜-匿名口令分享文本文件像拿快递一样取文件FileCodeBox - File Express Cabinet - Anonymous Passcode Sharing Text, Files, Like Taking Express Delivery for Files项目地址: https://gitcode.com/GitHub_Trending/fi/FileCodeBox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
