{"id":13524667,"url":"https://github.com/halo-dev/plugin-s3","last_synced_at":"2026-03-12T23:31:05.635Z","repository":{"id":65604536,"uuid":"581034927","full_name":"halo-dev/plugin-s3","owner":"halo-dev","description":"为 Halo 提供 S3 对象存储协议的存储策略","archived":false,"fork":false,"pushed_at":"2025-12-24T04:31:05.000Z","size":10251,"stargazers_count":39,"open_issues_count":29,"forks_count":26,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-12-25T18:53:04.769Z","etag":null,"topics":["halo","halo-plugin","s3"],"latest_commit_sha":null,"homepage":"https://halo.run/store/apps/app-Qxhpp","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/halo-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-12-22T05:14:06.000Z","updated_at":"2025-12-23T08:55:12.000Z","dependencies_parsed_at":"2023-10-16T16:37:26.195Z","dependency_job_id":"799337a8-8a37-41cb-a140-e626ec33bf6a","html_url":"https://github.com/halo-dev/plugin-s3","commit_stats":null,"previous_names":["halo-dev/plugin-s3","halo-sigs/plugin-s3"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/halo-dev/plugin-s3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-dev%2Fplugin-s3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-dev%2Fplugin-s3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-dev%2Fplugin-s3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-dev%2Fplugin-s3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/halo-dev","download_url":"https://codeload.github.com/halo-dev/plugin-s3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-dev%2Fplugin-s3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30449011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"ssl_error","status_checked_at":"2026-03-12T21:30:43.161Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["halo","halo-plugin","s3"],"created_at":"2024-08-01T06:01:12.293Z","updated_at":"2026-03-12T23:31:05.607Z","avatar_url":"https://github.com/halo-dev.png","language":"Java","funding_links":[],"categories":["Halo 2.0"],"sub_categories":["插件"],"readme":"# plugin-s3\n\n为 Halo 2.0 提供 S3 协议的对象存储策略，支持阿里云、腾讯云、七牛云等兼容 S3 协议的对象存储服务商\n\n## 使用方法\n\n1. 下载，目前提供以下两个下载方式：\n    - GitHub Releases：访问 [Releases](https://github.com/halo-dev/plugin-s3/releases) 下载 Assets 中的 JAR 文件。\n    - Halo 应用市场：\u003chttps://halo.run/store/apps/app-Qxhpp\u003e\n2. 安装，插件安装和更新方式可参考：\u003chttps://docs.halo.run/user-guide/plugins\u003e\n3. 配置存储策略：\n   * 在 Halo 后台管理系统中，点击左侧“附件”导航至附件管理页面，点击右上角的存储策略。\n   * 在存储策略管理界面中，您可以新建和编辑 S3 Object Storage 存储策略。\n4. 上传到存储策略：\n   * 在附件页面中点击上传按钮，选择好存储策略后上传文件即可上传到对应的对象存储中。\n   * 在 Halo 2.11 以上版本中可在 Halo 设置界面中设定文章附件、头像等的默认存储策略。\n5. 使用“关联 S3 文件”功能：\n   * 在左侧侧边导航栏中，点击工具，再点击 S3 关联。\n   * 在此界面中，您可以浏览并选择已在对象存储中但不是通过 Halo 上传的文件，关联后会在 Halo 生成相应的附件记录。这些文件现在可以方便地在 Halo 中管理和使用。\n6. 使用“解除 S3 关联”功能：\n   * 在附件页面中，找到由本插件管理的附件记录，点击更多操作（右侧的三个点）按钮，然后点击“解除 S3 关联”按钮。\n   * 此操作将仅删除 Halo 中的附件记录，而不会实际删除对象存储中的文件。如需恢复请使用“关联 S3 文件”功能。\n\n## 配置指南\n\n### Bucket 桶名称\n\n一般与服务商控制台中的空间名称一致。\n\n\u003e 注意部分服务商 s3 空间名 ≠ 空间名称，若出现“Access Denied”报错可检查 Bucket 是否正确。\n\u003e\n\u003e 可通过 S3Browser 查看桶列表，七牛云也可在“开发者平台-对象存储-空间概览-s3域名”中查看 s3 空间名。\n\n### Endpoint 访问风格\n\n请根据下方表格中的兼容访问风格选择，若您的服务商不在表格中，请自行查看服务商的 s3 兼容性文档或自行尝试。\n\n\u003e 风格说明：\u003cbr/\u003e\n\u003e 当Endpoint填写`s3.example.com`时\u003cbr/\u003e\n\u003e Path Style：SDK将访问`s3.example.com/\u003cbucket-name\u003e/\u003cobject-key\u003e`\u003cbr/\u003e\n\u003e Virtual Hosted Style：SDK将访问`\u003cbucket-name\u003e.s3.example.com/\u003cobject-key\u003e`\n\n### Endpoint\n\n此处统一填写**不带** bucket-name 的 Endpoint，SDK 会自动处理访问风格。\n\n想了解 s3 协议的 Endpoint 的配置可在服务商的文档中搜索 s3、Endpoint 或访问域名等关键词，一般与服务商自己的 Endpoint 相同。\n\n\u003e 例如百度云提供 `s3.bj.bcebos.com` 和 `\u003cbucket-name\u003e.s3.bj.bcebos.com` 两种 Endpoint，请填写`s3.bj.bcebos.com`。\n\n### Access Key \u0026 Access Secret\n\n与服务商自己 API 的 Access Key 和 Access Secret 相同，详情查看对应服务商的文档。\n\n### Region\n\n一般留空即可。\n\n\u003e 若确认过其他配置正确又不能访问，请在服务商的文档中查看并填写英文的 Region，例如 `cn-east-1`。\n\u003e \n\u003e Cloudflare 需要填写均为小写字母的 `auto`。\n\n### 上传目录\n\n上传到对象存储的目录，前后`/`可省略，例如`/halo`和`halo`是等价的。\n\n支持的占位符有：\n* `${uuid-with-dash}`：带有`-`的 UUID\n* `${uuid-no-dash}`：不带`-`的 UUID\n* `${timestamp-sec}`：秒时间戳（10位时间戳）\n* `${timestamp-ms}`：毫秒时间戳（13位时间戳）\n* `${year}`：年份\n* `${month}`：月份（两位数）\n* `${day}`：日期（两位数）\n* `${weekday}`：星期几，1-7\n* `${hour}`：小时（24小时制，两位数）\n* `${minute}`：分钟（两位数）\n* `${second}`：秒（两位数）\n* `${millisecond}`：毫秒（三位数）\n* `${random-alphabetic:X}`：随机的小写英文字母，长度为`X`，例如`${random-alphabetic:5}`会生成`abcde`。\n* `${random-num:X}`：随机的数字，长度为`X`，例如`${random-num:5}`会生成`12345`。\n* `${random-alphanumeric:X}`：随机的小写英文字母和数字，长度为`X`，例如`${random-alphanumeric:5}`会生成`abc12`。\n\n\u003e **示例**：\u003cbr/\u003e\n\u003e * `${year}/${month}/${day}/${random-alphabetic:1}`会放在`2023/12/01/a`。\u003cbr/\u003e\n\u003e * `halo/${uuid-no-dash}`会放在`halo/123E4567E89B12D3A456426614174000`。\n\n### 上传时重命名文件方式\n* **保留原文件名：** 使用上传时的文件名。\n* **自定义：** 使用`自定义文件名模板`中填写的模板，上传时替换相应占位符作后作为文件名。\n* **使用 UUID：** 上传时会自动重命名为随机的 UUID。\n* **使用毫秒时间戳：** 上传时会自动重命名为毫秒时间戳（13位时间戳）。\n* **使使用原文件名 + 随机字母：** 上传时会自动重命名为原文件名 + 随机的小写英文字母，长度请在`随机字母长度`中设置。\n* **使用日期 + 随机字母：** 上传时会自动重命名为日期 + 随机的小写英文字母，例如 `2023-12-01-abcdefgh.png`。\n* **使用日期时间 + 随机字母：** 上传时会自动重命名为日期时间 + 随机的小写英文字母，例如 `2023-12-01T09:30:01-abcdef.png`。\n* **使用随机字母：** 上传时会自动重命名为随机的小写英文字母，长度请在`随机字母长度`中设置。\n\n### 随机字母长度\n\n仅当`上传时重命名文件方式`为`使用原文件名 + 随机字母`或`使用日期 + 随机字母`或`使用日期时间 + 随机字母`或`使用随机字母`时出现，用于设置随机字母的长度。\n\n### 自定义文件名模板\n\n仅当`上传时重命名文件方式`为`自定义`时出现，用于设置自定义文件名模板。\n\n支持的占位符有：\n* `${origin-filename}`：原文件名\n* `${uuid-with-dash}`：带有`-`的 UUID\n* `${uuid-no-dash}`：不带`-`的 UUID\n* `${timestamp-sec}`：秒时间戳（10位时间戳）\n* `${timestamp-ms}`：毫秒时间戳（13位时间戳）\n* `${year}`：年份\n* `${month}`：月份（两位数）\n* `${day}`：日期（两位数）\n* `${weekday}`：星期几，1-7\n* `${hour}`：小时（24小时制，两位数）\n* `${minute}`：分钟（两位数）\n* `${second}`：秒（两位数）\n* `${millisecond}`：毫秒（三位数）\n* `${random-alphabetic:X}`：随机的小写英文字母，长度为`X`，例如`${random-alphabetic:5}`会生成`abcde`。\n* `${random-num:X}`：随机的数字，长度为`X`，例如`${random-num:5}`会生成`12345`。\n* `${random-alphanumeric:X}`：随机的小写英文字母和数字，长度为`X`，例如`${random-alphanumeric:5}`会生成`abc12`。\n\n\u003e **示例**：\u003cbr/\u003e\n\u003e 当原始文件名为`image.png`时\u003cbr/\u003e\n\u003e * `${origin-filename}-${uuid-with-dash}`会生成`image-123E4567-E89B-12D3-A456-426614174000.png`。\u003cbr/\u003e\n\u003e * `${year}-${month}-${day}T${hour}:${minute}:${second}-${random-alphanumeric:5}`会生成`2023-12-01T09:30:01-abc12.png`。\u003cbr/\u003e\n\u003e * `${uuid-no-dash}_file_${random-alphabetic:5}`会生成`123E4567E89B12D3A456426614174000_file_abcde.png`。\u003cbr/\u003e\n\u003e * `halo_${origin-filename}_${random-num:3}`会生成`halo_image_123.png`。\n\n### 重复文件名处理方式\n\n* **加随机字母数字后缀：** 如遇重名，会在文件名后加上4位的随机字母数字后缀，例如`image.png`会变成`image_abc1.png`。\n* **加随机字母后缀：** 如遇重名，会在文件名后加上4位的随机字母后缀，例如`image.png`会变成`image_abcd.png`。\n* **报错不上传** 如遇重名，会放弃上传，并在用户界面提示 Duplicate filename 错误。\n\n## 部分对象存储服务商兼容性\n\n|服务商|文档|兼容访问风格|兼容性|\n| ----- | ---- | ----- | ----- |\n|阿里云|\u003chttps://help.aliyun.com/document_detail/410748.html\u003e|Virtual Hosted Style|✅|\n|腾讯云|\u003chttps://cloud.tencent.com/document/product/436/41284\u003e|Virtual Hosted Style / \u003cbr\u003ePath Style|✅|\n|七牛云|\u003chttps://developer.qiniu.com/kodo/4088/s3-access-domainname\u003e|Virtual Hosted Style / \u003cbr\u003ePath Style|✅|\n|百度云|\u003chttps://cloud.baidu.com/doc/BOS/s/xjwvyq9l4\u003e|Virtual Hosted Style / \u003cbr\u003ePath Style|✅|\n|京东云|\u003chttps://docs.jdcloud.com/cn/object-storage-service/api/regions-and-endpoints\u003e|Virtual Hosted Style|✅|\n|金山云|\u003chttps://docs.ksyun.com/documents/6761\u003e|Virtual Hosted Style|✅|\n|青云|\u003chttps://docsv3.qingcloud.com/storage/object-storage/s3/intro/\u003e|Virtual Hosted Style / \u003cbr\u003ePath Style|✅|\n|网易数帆|\u003chttps://sf.163.com/help/documents/89796157866430464\u003e|Virtual Hosted Style|✅|\n|Cloudflare|\u003chttps://developers.cloudflare.com/r2/data-access/s3-api/\u003e|Virtual Hosted Style / \u003cbr\u003ePath Style|✅|\n| Oracle Cloud |\u003chttps://docs.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm\u003e|Virtual Hosted Style / \u003cbr\u003ePath Style|✅|\n|又拍云|\u003chttps://help.upyun.com/knowledge-base/aws-s3%e5%85%bc%e5%ae%b9/\u003e|Virtual Hosted Style / \u003cbr\u003ePath Style|✅|\n|自建minio|\\-|Path Style|✅|\n|华为云|文档未说明是否兼容，工单反馈不保证兼容性，实际测试可以使用|Virtual Hosted Style|❓|\n|Ucloud|只支持 8MB 大小的分片，本插件暂不支持\u003cbr\u003e\u003chttps://docs.ucloud.cn/ufile/s3/s3_introduction\u003e|\\-|❌|\n\n## 开发环境\n\n```bash\n./gradlew build\n```\n\n修改 Halo 的配置文件\n\n```yaml\nplugin:\n  runtime-mode: development # development, deployment\n  classes-directories:\n    - \"build/classes\"\n    - \"build/resources\"\n  lib-directories:\n    - \"libs\"\n  fixedPluginPath:\n    - \"path/to/plugin-s3\"\n```\n\n启动 Halo 之后即可在后台插件管理看到此插件。\n\n## 生产构建\n\n```yaml\n./gradlew build\n```\n\n构建完成之后，可以在 `build/libs` 目录得到插件的 JAR 包，在 Halo 后台的插件管理上传即可。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalo-dev%2Fplugin-s3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalo-dev%2Fplugin-s3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalo-dev%2Fplugin-s3/lists"}