从零搭建HFS文件服务器：一台闲置电脑变身共享文件站的完整实战指南

从零搭建HFS文件服务器：一台闲置电脑变身共享文件站的完整实战指南

【免费下载链接】hfsHFS is a web file server for your computer. Share folders or even a single file thanks to the virtual file system.项目地址: https://gitcode.com/gh_mirrors/hf/hfs

某天下午，你的团队需要交换一批大文件——几个 GB 的设计源文件、一整季的视频素材。微信传不动，U 盘拷来拷去折腾一上午，网盘上传要等半小时还限速，企业云盘一年几千块却只用到十分之一。如果你手头恰好有一台不常关机的电脑，那么答案可能就藏在一个叫HFS的开源文件服务器里：它能把任意一台电脑变成一台"随时可取、速度自控"的文件共享站，文件直接从你的硬盘流出，不走云端，不限容量，不按月收费。

这篇文章不打算按"功能介绍清单"的套路来写，而是把你放进一个真实的使用过程里：从第一次跑通、到多人共用、到对外开放、再到长期维护，每到一个阶段会遇到什么问题、该用什么配置解决、配置长什么样，一次讲清楚。你可以把它当作一份"跟着做就能成功"的作业手册。

上图来自项目仓库：在 Windows 资源管理器中右键文件，即可快速把文件加入 HFS 文件服务器的共享列表，省去手动维护目录的麻烦。

第一阶段：先把服务器跑起来

你要解决的问题

很多人第一次接触 HFS 时，最大的心理障碍是"这是不是又要配半天环境"。好消息是：HFS 是免安装的软件，解压即用，连数据库都不用建。你需要的只是三步：下载对应系统的压缩包 → 解压 → 双击运行。

启动之后，HFS 会自动打开浏览器并跳转到管理面板（默认地址是http://localhost:端口号/~/admin）。从这里你就能直观地添加要共享的文件夹、创建账号、查看实时连接。如果浏览器没有自动弹出，多半是因为你在无图形界面的服务器上运行，此时打开终端，在 HFS 控制台里敲一句：

create-admin 你的管理密码

这行命令会立刻创建一个管理员账号，之后用这个账号登录管理面板即可。

怎么确认配置存在哪里

HFS 的一切设置最终都落在config.yaml这个文本文件里，但它放在哪，取决于你用什么系统。启动时的控制台前几行会打印一条working directory (cwd)信息，那才是它真正存放的位置：

• Windows 下，默认和hfs.exe放在同一目录；
• Linux / macOS 下，默认放在~/.hfs目录；
• 想换个地方放？启动时加参数--cwd 某个目录即可，配置、日志、插件都会跟着挪过去。

适用场景：需要把配置目录放到数据盘、或用脚本批量部署时，--cwd能帮你把"程序文件"和"配置数据"彻底分离，重装程序不丢配置。

五种改配置的入口，新手记住前两个就够了

HFS 的配置方式非常灵活，同一个设置可以用五种方式修改，它们最终的效果完全一致，你可以按场景任选：

注意事项：命令行参数和环境变量的优先级高于配置文件；如果你用 Docker 部署，记得设置DISABLE_UPDATE=1，避免容器里自动更新导致意外。

你的第一份最小配置文件

哪怕是"零配置"，HFS 也有自己的默认值（比如端口 80）。但为了让行为完全可控，建议从一份最小的config.yaml开始：

port: 8080 # HTTP 端口，默认 80，80 被占用就换一个 title: 团队素材库 # 浏览器标签页上显示的名字 open_browser_at_start: false # 服务器模式下别自动弹浏览器 localhost_admin: true # 本机访问管理面板免登录，方便调试

⚠️ 注意：上面这份配置只适合内网调试。一旦准备对外提供服务，请务必先读完下文第四阶段的安全清单再上线。

第二阶段：把散落的文件"虚拟"地归拢到同一棵树下

你要解决的问题

真实工作中，共享内容往往散落在各处：设计稿在D:\projects\design，视频素材在/data/media，还有一个网盘同步目录在别处。如果要求你全部挪到一个文件夹里，既打乱原有工作习惯，又容易造成重复拷贝。HFS 的**虚拟文件系统（Virtual File System，简称 VFS）**就是为此而生的。

你可以把 VFS 想象成一个商场里的虚拟货架：货架的格子可以指向仓库里任意角落的真实货位，顾客只看到货架上的陈列，完全不知道（也不关心）东西实际存放在哪。HFS 里的 VFS 就是这排货架，每个格子（节点）可以指向一个真实目录、一个真实文件，甚至一条外部网址。

怎么把真实目录挂进来

最省事的方式是直接绑定一个磁盘路径作为根节点：

vfs: source: /data/public

这样访问者的首页就会直接展示/data/public的内容。但如果你的内容分散在多处，用children把它们组装成一个虚拟树：

vfs: children: - name: 设计稿 # 显示给访问者的名字，可自定义 source: D:/projects/design # 指向真实磁盘路径 - name: 视频素材 source: /data/media - name: 公司官网 # 还可以挂一个外部链接节点 url: https://example.com target: _blank

适用场景：内容散落多盘、需要对访问者隐藏真实目录结构、想给同一个目录起一个更友好的名字时，children方案是首选。

注意事项：name和source至少提供一个；只写source不写name时，HFS 会自动用路径的最后一段作为名字。

VFS 节点字段速查

下面这张四列速查表覆盖了节点上最常用的字段，后面第三、四阶段还会反复用到其中的权限类字段：

第三阶段：多人共用时，权限这样设最省心

你要解决的问题

内网跑通之后，很快会进入"几个人共用"的阶段。此时最大的难题不是技术，而是如何用最简单的方式说清楚"谁能干什么"。HFS 把所有权限统一抽象成一种叫做Who的描述符，看懂它，就掌握了整个权限体系的一半。

你可以把Who想象成门禁卡上的权限等级，一共五档：

用账户 + 组搭一套最小权限模型

HFS 的账户体系有个很巧的设计：没有密码的账户就是"组"。组不能登录，但可以被其他账户用belongs挂靠，从而一次性继承组上的权限。这就像工牌上的"部门标签"——你不需要逐个给员工授权，只要给"部门"授权，新员工挂进部门就自动拥有权限。

下面是一份典型的"管理员 + 普通员工 + 访客"模型：

accounts: admin: password: 换成强密码 # 保存后会自动转为加密形式 srp admin: true # 允许登录管理面板 ignore_limits: true # 不受限速/并发限制 employee_group: # 无密码 = 组，仅供挂靠 guest: password: guest2024 belongs: [employee_group] # 把访客也挂进员工组，继承权限 days_to_live: 30 # 30 天后自动过期，适合临时账号 allow_net: 192.168.1.0/24 # 只允许内网登录

配上 VFS 里的权限声明：

vfs: children: - name: 公开区 source: /data/public can_read: true # 游客也能看 - name: 项目区 source: /data/projects can_read: [employee_group] # 只有员工组能下载 can_upload: [admin] # 只有管理员能上传 - name: 机密区 source: /data/secret can_see: false # 完全不出现在列表里 can_read: [admin]

适用场景：超过 3 个人共用、需要区分游客/员工/管理员三类角色的场景，这套模型可以覆盖 90% 的需求。

注意事项：days_to_live会在该账户首次登录时才开始计时，适合发放临时协作账号；allow_net用网段掩码限制登录来源，公司内部共享时建议给所有员工账号都加上。

用文件掩码做批量规则

当你想对"某一类文件"而不是"某一个目录"设置权限时，就用masks。它的语法是"文件通配符 → 要覆盖的权限"，规则从上到下优先级递减，内层节点的规则优先于外层：

vfs: source: /shared masks: "**/*.mp4|**/*.mkv": # 所有视频，注意用两个*匹配子目录 can_read: [vip] # 视频只给 VIP "**/backup/**": # 备份目录整个隐藏 can_see: false can_read: false "*.log|files|": # 后缀 |files| 表示只匹配文件不匹配文件夹 can_see: false # 各种日志文件不让外人看到

一句话记忆：外层规则是"默认值"，内层规则是"例外"；|files|只碰文件、|folders|只碰文件夹。想开放某个子目录、又不想动父目录权限时，就在该子节点上单独写权限覆盖父级。

第四阶段：对外开放前，先过一遍安全清单

你要解决的问题

一旦决定让外部人员（客户、异地同事）访问你的文件服务器，就意味着把一台电脑暴露在公网上。此时要考虑的就不再是"方便"，而是哪些口子不该开着。HFS 的安全项并不复杂，按下面的清单走一遍，就能把绝大多数风险挡在门外。

第一项：用 HTTPS 给传输加把锁

HTTP 明文传输意味着密码和文件内容在网络上是裸奔的。HFS 支持两种方式启用 HTTPS：

• 自备证书：把证书和私钥路径填进配置；
• 自动签发（ACME）：提供域名后，HFS 自动向证书机构申请免费证书，临近过期还会自动续期——这是最省心的方式。

https_port: 443 # 开启 HTTPS 端口 force_https: true # 所有 HTTP 请求自动跳转到 HTTPS acme_domain: share.example.com # 你的域名，需要提前把 A 记录指向本机 acme_renew: true # 自动续期，别让它过期

适用场景：任何对外提供服务的部署都建议开启。注意事项：ACME 自动签发要求该端口（默认 443）能从公网访问，且域名解析正确，否则申请会失败。

第二项：收紧管理后台的入口

管理面板是整台服务器权限最高的地方，绝不能裸奔在公网上。两个配置项专门管这件事：

localhost_admin: false # 关闭"本机免密进后台"，改成必须登录 admin_net: 192.168.1.0/24 # 只允许内网 IP 段访问后台

注意事项：admin_net是"最后一根保险丝"——即便管理员密码泄露，非白名单 IP 也进不了后台。远程管理时可以把你的固定公网 IP 加进白名单，而不是直接设为any。

第三项：黑名单与地理防火墙

对付扫描器和恶意 IP，HFS 提供了两层过滤：block规则用于精确封锁，地理防火墙（GeoIP）用于按国家一刀切。

block: # IP 黑名单，支持单个 IP 和网段 - ip: 203.0.113.7 - ip: 198.51.100.0/24 geo_enable: true # 打开地理识别（每月自动更新 2MB 的数据库） geo_allow: false # false = 黑名单模式 geo_list: [CN, RU] # 名单里的国家直接拒绝 geo_allow_unknown: false # 识别不出的请求也拒绝（更严格）

⚠️ 提示：地理防火墙对内网共享没有意义，它只在你确定"这个业务永远不服务某些地区"时才有价值。误配名单可能导致自己人都进不来，上线前务必用小范围验证。

第四项：让暴力破解者自己放弃

项目内置了antibrute（防暴力破解）插件，并且默认就是启用的。它会为每个登录失败的 IP 和账户逐步增加等待时间：第一次失败等 5 秒，第二次 10 秒，以此类推；连续失败超过阈值后直接临时封禁。你可以在管理面板的插件配置里调整它的行为，也可以直接在配置文件里写：

enable_plugins: [antibrute] # 默认就包含它，这里显式声明 plugins_config: antibrute: increment: 5 # 每次失败递增 5 秒等待 blockAfter: 20 # 失败 20 次后封 IP blockForHours: 24 # 封禁 24 小时 exclude: 192.168.1.0/24 # 内网 IP 不参与封禁

第五阶段：人多了、文件大了，怎么让它又快又稳

你要解决的问题

共享进入常态化后，你会开始听到三种抱怨："下载把整个办公室的网都卡死了""几百个文件的小文件夹下载太麻烦""视频加载半天转不出来"。这三个问题分别对应带宽控制、并发限制、即时打包与缓存三件事。

给带宽和并发装上"限速阀"

HFS 的限速支持"全局 / 单 IP / 单账户"三个维度，三者可以叠加生效。把全局值当成总闸，把单 IP 值当成每个用户的分水表：

max_kbps: 102400 # 全局总带宽上限，100MB/s max_kbps_per_ip: 20480 # 单个 IP 最多 20MB/s，防一人占满 max_downloads: 20 # 全服务器同时最多 20 个下载任务 max_downloads_per_ip: 3 # 同一 IP 最多 3 个并发下载 max_downloads_per_account: 5 # 登录账户每人最多 5 个并发

适用场景：共享网络（办公室、宿舍）强烈建议配置；独享大带宽的服务器可以只设并发数。注意事项：max_downloads_per_account只对已登录的连接生效，且优先级最高——游客不受它约束，所以对外开放时别忘了同时设per_ip。

让整个文件夹变成一个 ZIP 下载

HFS 的一个亮点是文件夹即时打包：访问者勾选任意文件/文件夹，服务器会现场把它们压缩成一个 ZIP 流式下发，不需要你在磁盘上预先生成压缩包。唯一的代价是"算大小"需要时间，对超大文件夹可以关掉这个计算让下载立即开始：

zip_calculate_size_for_seconds: 0 # 0 = 跳过大小计算，立即开始打包

注意事项：设成 0 后，访问者看到的文件夹大小可能不准确（显示为未知），换取的是秒开体验。追求显示精确度的话保留默认值 1 即可。

缓存与超时的小调整

几个容易被忽略但对体验影响明显的参数：

cache_control_disk_files: 3600 # 浏览器缓存磁盘文件 1 小时，减少重复请求 file_timeout: 10 # 读取文件超时从默认 3 秒放宽到 10 秒，适合慢速磁盘

适用场景：图片/静态资源多的目录，调大缓存能显著降低服务器压力；机械硬盘或网络挂载盘上，加大file_timeout能避免偶尔的读取超时误判。注意缓存时间别设太大，否则更新文件后用户端可能一直看到旧版本。

第六阶段：长期运行后的维护与救急

你要解决的问题

服务器跑上几个月后，新问题会变成"慢性病"：日志文件越滚越大、磁盘被上传文件占满、忘了管理员密码、域名 IP 变了没人发现。这一节集中解决这些"时间带来的问题"。

让日志自己"归档"

默认情况下 HFS 每周轮转一次日志（把旧日志压缩成归档文件，再开新文件）。你也可以改成按天、按月，或干脆关闭：

log: access.log # 访问日志文件 error_log: error.log # 错误日志文件 log_rotation: daily # 每天轮转一次（可选 weekly / monthly） dont_log_net: 127.0.0.1|::1 # 本地回环地址的请求不进日志，减少噪音 log_api: false # 是否记录 API 调用，调试时再打开

注意事项：日志轮转解决的是"单文件过大"，不是"历史日志堆积"。配合系统 cron 定期清理超过 30 天的归档日志，效果最好。

给上传加上"磁盘红线"

磁盘写满是文件服务器最常见的宕机原因之一。HFS 提供两个保险：

min_available_mb: 500 # 可用磁盘低于 500MB 时，拒绝新的上传 delete_unfinished_uploads_after: 3600 # 1 小时后仍未完成的半截上传自动删除 split_uploads: 100 # 大文件按 100MB 分块上传，断线后可从断点续传

适用场景：允许用户上传的部署必须配置min_available_mb；split_uploads对弱网/移动端上传体验提升明显，代价是每个文件会产生多个分块请求。

忘了密码、域名变了这类救急问题

• 忘管理密码：在 HFS 控制台执行create-admin 新密码，立刻重建管理员。
• 改配置忘了在哪个文件：看启动日志里的working directory (cwd)一行，配置就在那个目录下。
• 家里宽带 IP 老变：HFS 支持内置的动态 DNS 客户端，把更新地址填进配置，服务器会定期上报当前 IP：

dynamic_dns_url: | https://api.dynu.com/nic/update?hostname=myhost.example.com&myip=> https://backup.ddns.net/update?ip=>.*success

第一行末尾的>表示"把服务器检测到的公网 IP 填到这个位置"，第二行>.*success则是用正则判断更新是否成功。多条地址可以各占一行，互为备份。

最后一页：你现在就可以开始动手

回看整个旅程，其实只有四步：跑起来（第一阶段）→把目录挂成虚拟树（第二阶段）→按角色设权限（第三阶段）→按暴露范围决定安全与性能投入（第四、五阶段）。HFS 最大的优点是"渐进式配置"——它不需要你在第一天就规划好一切，先在内网用起来，再随着需求一点点加配置，每一步都是可逆的。

如果你走的是从源码构建的路线，也可以直接克隆仓库自己研究：

git clone https://gitcode.com/gh_mirrors/hf/hfs

读到这里，你的电脑其实已经具备成为一台专业文件共享服务器的全部条件。找一个闲置目录，把它挂进 VFS，然后用手机浏览器打开你的服务器地址试试——当看到文件在你自己的"云盘"里流畅下载的那一刻，你会明白为什么这么个小工具能流行这么多年。

给你留三个待办：① 给服务器配一个正式的管理员密码；② 给对外开放的目录过一遍第四阶段的安全清单；③ 在日历上记一个每月维护提醒，检查日志大小和磁盘余量。剩下的，交给 HFS 就好。

【免费下载链接】hfsHFS is a web file server for your computer. Share folders or even a single file thanks to the virtual file system.项目地址: https://gitcode.com/gh_mirrors/hf/hfs