{"id":36467062,"url":"https://github.com/koihuang/speedfs","last_synced_at":"2026-01-15T02:30:40.526Z","repository":{"id":215283775,"uuid":"738560396","full_name":"koihuang/speedfs","owner":"koihuang","description":"轻量级高性能高可用分布式文件存储","archived":false,"fork":false,"pushed_at":"2024-03-27T10:01:53.000Z","size":158,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-21T04:56:46.071Z","etag":null,"topics":["dfs","distributed-file-storage","distributed-file-system","filesystem"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koihuang.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}},"created_at":"2024-01-03T14:06:49.000Z","updated_at":"2024-01-12T08:41:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"f05ff618-2618-4d84-a9d3-935c0a6ad7f9","html_url":"https://github.com/koihuang/speedfs","commit_stats":null,"previous_names":["koihuang/speedfs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/koihuang/speedfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koihuang%2Fspeedfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koihuang%2Fspeedfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koihuang%2Fspeedfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koihuang%2Fspeedfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koihuang","download_url":"https://codeload.github.com/koihuang/speedfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koihuang%2Fspeedfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28441307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dfs","distributed-file-storage","distributed-file-system","filesystem"],"created_at":"2026-01-12T00:06:04.395Z","updated_at":"2026-01-15T02:30:40.494Z","avatar_url":"https://github.com/koihuang.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# speedfs\n\n## 介绍\nspeedfs是一个轻量级高性能分布式文件存储系统。适合只需要一个高可用性能较好的分布式文件存储系统的2B或2G的小型项目。\n\n主要特性：\n* 去中心化高可用:集群的所有节点都是对等的，可同时读写\n* 高性能:上传、下载、节点间通信采用http协议;节点之间异步同步\n* 部署、运维方便:配置简单直观、部署运维脚本完备，开箱即用\n\n## 核心设计\n本项目深度参考了go-fastdfs(https://github.com/sjqzhang/go-fastdfs) 的实现。设计上做了一些精简，一致性方面做了一些优化。\n* 文件路径命名设计\n  * 文件命名：HHmmss_uuid_filename 解释：上传时时刻的时分秒_uuid_文件名 例：151802_b918c350b8cb4318acbcc0dafab369f6_你好世界.txt\n  * 文件全路径：SPEEDFS_PATH/file/yyyyMMdd/HHmmss_uuid_filename 解释：speedfs的部署目录/file/上传时刻的年月日/文件名 例：/root/test/speedfs/file/20240103/160151_3f0db6c3d1bc4db1afaa34bb2456c95b_你好世界.png\n  * 文件对外暴露路径：/yyyyMMdd/HHmmss_uuid_filename 应用使用此路径调接口下载文件\n\n* 自动修复\n每天凌晨3点每个节点会比较自己和其他节点的差异，每个节点只会同步自己没有的，别的节点有的。\n\n## speedfs的数据一致性说明：\n* 写文件\n每次上传都会使用uuid生成唯一命名的文件名，即使两次上传同一份文件，对于speedfs来说也会分别保存，每次返回的路径也不一样。因此对写数据来说不存在并发冲突问题。文件上传到调用的节点成功后，会异步通知其他节点同步数据。\n* 读文件\n访问的节点有则返回，没有从其他节点依次尝试访问查询，如果则同步拉取到本地然后返回。\n* 删文件\n调用节点删除成功后，节点会异步通知其他节点删除。\n\n从上面读写删的描述看，单纯的写和读不会有一致性问题，删除在极端情况下会有删除不干净的情况，比如在上传文件异步同步的期间突然调用了删除接口，可能存在删除不干净的情况。如果应用本身做了删除会不会再查看的操作那么即使出现删除不干净的情况也不会影响业务。\n\n## 安装部署\n安装包可通过release页面下载,也可以自行编译\n### 安装包下载\n从release页面下载\nhttps://github.com/koihuang/speedfs/releases\n\n![安装包下载](./doc/img/release-pack.png)\n### 自行编译\n默认当前机器平台编译\n```shell\n#项目根目录执行\nmake pack\n```\n交叉编译命令\n```shell\nmake pack target=linux-amd64\nmake pack target=linux-arm64\nmake pack target=darwin-amd64\nmake pack target=darwin-arm64\n```\n\n### 安装\n* 解压压缩包\n\n![解压安装包](./doc/img/pack.png)\n\n### 初始化\n\n```shell\n./init.sh\n```\n执行后会在当前目录生成file(存文件),log(存日志),config(存配置)等目录\n\n![init](./doc/img/init.png)\n\n```shell\n.\n├── log #日志\n├── file #文件目录\n├── config #配置\n│   └── config.json #配置文件\n├── init.sh \t\t\t#初始化脚本\n├── restart.sh\t\t\t#重启脚本\n├── speedfs\t\t\t    #speedfs二级制\n├── start.sh\t\t\t#启动脚本\n└── stop.sh\t\t\t\t#停止脚本\n```\n#### 修改配置\n\n配置文件为json格式config/config.json配置项说明\n```shell\n{\n    \"port\": 9999, #http监听服务端口,默认9999,意寓服务经久不断\n    \"advertise-ip\": \"192.168.31.192\", #内网ip,高可用集群中其他节点可以访问的ip,默认初始化为内网ip\n    \"peers\": [ #集群地址列表,所有节点都配同样的列表,当前节点地址的ip部分需要和advertise-ip保持一致\n        \"192.168.31.192:9999\"\n    ]\n}\n```\n配置样例:\n\n假设在192.168.31.191,192.168.31.192两台机器部署高可用集群,那么配置为\n```shell\n#192.168.31.191配置\n{\n    \"port\": 9999, \n    \"advertise-ip\": \"192.168.31.191\", \n    \"peers\": [ \n        \"192.168.31.191:9999\",\"192.168.31.192:9999\"\n    ]\n}\n```\n```shell\n#192.168.31.192配置\n{\n    \"port\": 9999, \n    \"advertise-ip\": \"192.168.31.192\", \n    \"peers\": [ \n        \"192.168.31.191:9999\",\"192.168.31.192:9999\"\n    ]\n}\n```\n\n#### 启动\n```shell\n./start.sh\n```\n#### 其他运维命令\n```shell\n./restart.sh #重启\n./stop.sh    #停止服务\n```\n## 接口文档\n### 上传接口\n请求参数\n- **方法：** `POST`\n- **路径：** `/upload`\n- **参数：**\n  - `file` (表单参数)：要上传的文件\n响应\n```shell\n{\n  \"status\": \"success\", #成功:succss 失败:fail\n  \"code\":0, #错误码,默认0,系统错误:1000\n  \"msg\":\"\"  #错误信息\n  \"data\": {\n    #文件路径\n    \"filepath\":\"/20240103/160151_3f0db6c3d1bc4db1afaa34bb2456c95b_xxx.png\",\n    #下载链接\n    \"downloadUrl\":\"http://192.16.31.192:9999/20240103/160151_3f0db6c3d1bc4db1afaa34bb2456c95b_xxx.png\"\n  }\n}\n```\n应用端可选择存文件路径,好处是文件迁移到其他ip的机器也不影响,坏处是下载的时候需要拼接ip端口\n\n### 下载接口\n请求参数\n- **方法：** `GET`\n- **路径：** `/{filepath}`\n- **参数：**\n  - `filepath` (路径参数)：要下载文件的路径\n\n响应\n```shell\n文件写入输出流\n```\n### 删除接口\n请求参数\n- **方法：** `POST`\n- **路径：** `/delete`\n- **参数：**\n  - `filepath` (表单参数)：要删除的文件路径\n    响应\n```shell\n{\n  \"status\": \"success\", #成功:succss 失败:fail\n  \"code\":0, #错误码,默认0,系统错误:1000\n  \"msg\":\"\"  #错误信息\n  \"data\": null\n}\n```\n## TODO\n- [ ] 权限验证\n- [ ] 自动修复服务重启间隔期间的文件\n- [ ] 客户端调用样例\n- [ ] 单元测试\n- [ ] docker\n- [ ] 压测\n- [ ] gc-tracker\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoihuang%2Fspeedfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoihuang%2Fspeedfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoihuang%2Fspeedfs/lists"}