# AFI - gossa 的现代化改进与维护分支

本项目 fork 自 [Gossa, 由 Pierre Dubouilh 及 Gossa Authors 开发维护](https://github.com/pldubouilh/gossa), 并重新初始化 git.

AFI(Agile File Interface) 是 Go 编写的轻量级文件服务器, 是基于 Gossa 的现代化增强维护分支  

特色:  

- 后端代码量低, 易于审查; 我们(虽然目前只有一个维护者 但是还是称"我们" :))在 Gossa 的基础上进行了大量重构, 大幅增强了前后端的可维护性并提升了效率
- 清晰现代且轻量的网页界面, 比原版 Gossa 的信息量更高且更悦目, 不依赖任何 web 框架, 操作无动画不拖泥带水, 除字体外无任何外部资源引用 (显然我们的前端不会引用 is-odd 和 is-even, 也不会因 left-pad 而崩溃 :D)
- 相较于 FileBrowser, AFI 易于嵌入至 `<iframe>` 且速度极快, 您可以将它用作图床或美观地嵌入到自己的博客附件页
- 单个可执行文件, 无需数据库, 速度极快, 方便快速部署
- 与 FUSE 文件系统兼容 (如 rclone 实例配置的网络挂载)
- 支持拖拽上传文件和目录, 并以归档(.zip)形式方便地下载任意目录
- 支持 MD5, SHA-1, SHA-256, SHA-512 文件校验和的远程解算
- 支持通过 `DESCRIPT.ION` 文件存储的备注元信息
- 完备的键盘操作支持
- 基本的用户管理系统 (基于 HTTP Basic Authication), 我们移除了 Gossa 单一的只读/可写模式 (即 -ro 参数), 并保留了未登录状态下的默认只读模式
- 支持跳过隐藏项目 (以 `.` 开头的文件/目录)
- 开发/生产模式分离, 便于免编译重载前端资源
- 同时提供简易的 RPC 调用接口, 并加入了 WebDAV 接口便于编程与挂载, 网页用户界面的 JavaScript 使用前者
- 低占用高性能, 网页用户界面每秒可承受万级以上响应并持续保持毫秒级低延迟, 接口性能更高
- 默认启用 gzip 压缩, 并为 iframe 嵌入优化
- 性能高效, 提供毫秒级响应, 用户使用体验不让位于技术审美与性能
- 改进的安全设计, 相较原项目增加了对 XSS 等攻击的防护

## 安全与不安全设计

考虑到此程序可能被使用的场景与便于方案选型, 笔者在此指出此程序存在的问题, 以免产生虚假的安全感  
如果您在为安全性抉择是否使用此项目, 我们高度建议您不要使用它  
如您发现了其他可能的漏洞, 请在 issues 指出, 若属实, 笔者会将其修复或加入下方列表, 并且将您的名字加入致谢名单  

安全建议:

- 强烈建议配置一个 nginx 反向代理并向外部阻断应用本身的端口
  - 必要时设置超时, 限制请求大小与频率
  - 如果可以的话, 最好套一层 WAF
- 配置好 SSL 证书, 完全避免使用 HTTP
- 必要时设置磁盘配额
- 一定不要把分享目录设置为用户目录或根目录
- 使用环境变量 `AFI_AUTH` 而不是参数设置用户验证键值对
- 使用普通用户, chroot 或容器运行


安全设计:
- 可防止路径穿越攻击
- 有基本的权限管理系统 (基于 HTTP Basic Authentication)

不安全设计:
- 不能防范且无法容忍的攻击
  - 没发现, 但这里没写不等于没有, 欢迎通过 issues 提出
- 未防范但几乎不可能成功的攻击
  - Timing Attack (未防范, 密码在后端明文比较, 但可通过设置较不寻常的用户名规避) -> 我们未来大概率不会改
- 能防范的攻击
  - XSS 攻击
  - Symlink 逃逸攻击 (可选且默认开启, 但开启后您就不能使用 linux 的符号链接便利了)
  - 路径穿越攻击
  - CSRF 攻击 (HTTP Basic Authentication 天然防范)
- 其他不安全设计:
  - 密码以明文形式传输 (因此千万不要在非 HTTPS 环境公网部署或预留 HTTP 访问, 除非您完全不配置用户(相当于原版 Gossa 的只读模式)) -> 我们未来会改, 但会在增加 Argon2 的基础上保留明文与 MD5 模式
  - 后端密码参数化 (可登录服务器后轻松用 ps 或类似工具查看), 已经可以环境变量安全设置, 但不会移除 `-auth` 选项以防您需要测试或使用 PaaS 部署
  - DoS 攻击 - 我们认为这件事应该由 nginx 反向代理预防
  - 请求大小和配额无限制导致的超大文件占用和可能导致的 OOM 崩溃 - 我们认为这件事应该由 nginx 反向代理或磁盘配额限制预防, 并且就事实而言, 内部威胁不在模型内, 这很大程度上是有权限的用户行为不当引起的问题
  - 无自带的响应超时: 可能招致 Slowloris 服务瘫痪 - 但这可由 nginx 反向代理预防
  - 权限提升风险: AFI 以什么用户运行, 就有什么权限 - 如果以 root 运行且将分享目录设置为根目录, 则任何登录用户都能删除系统, 或者通过上传 `.ssh/authorized_keys` 或 `.bashrc` 远程控制您的服务器操作系统 -> 我们改不了
- 未默认杜绝的隐私问题:
  - 外部字体 Referer 泄露 (仅会得知您访问的链接, 但如果您需要, 可以移除前端中引用的在线字体链接) 就事实而言, 我们认为外部字体提供商不太可能有收集这种数据的动机, 但如果您在高敏感内网部署, 则您可能不希望任何外部服务能够得知内网的文件结构
  - 日志可能泄漏敏感信息 (可以通过修改源代码编译解决, 但我们提供的二进制释出没有移除敏感信息输出)
- 未对特定安全需求进行的设计:
  - 不自带 https 服务器 - 如果您在公网直接跑这个程序并且使用它, 您等同于裸奔
  - 不支持细粒度权限控制 (我们支持配置多个用户, 但登录后您就只能是对分享目录下的文件完全可写(取决于运行 afi 的用户)的状态了)
  - 没有自带的防暴力破解机制
  - 没有操作审计日志
  - 没有密码哈希存储 (后端明文比较)
可能被误解为是不恰当的设计:
- 代码中不恰当的注释, 但这些注释(html, js 和 css 中的)事实上会被 go 的 embed 清除(即使有 "dev" tag), 因此您不必担心这些注释会随页面传递给浏览器, 在"查看源代码页"呈现给用户

> 注意: 这些不安全设计并非都是运维或服务器管理员能解决的, 因此请量需求而行

## 使用方法

```sh
$ ./afi --help
```

## 编译

```bash
# go vet && go fmt # 可选
go build -o afi # 单文件, 自包括 web 资源, 便于部署
go build -tags dev -o afi-dev # 使用运行目录(优先)或程序目录下的 web 资源 (ui 目录)
```

> 如果您此前没有接触过 go, 并且讨厌 go 会在您的用户主目录创建一个 "go" 文件夹, 您可以设置以下环境变量把 go 的存储位置改成隐藏的 ".go" (仅 linux)

```text
export GOPATH=$HOME/.go
export GOMODCACHE=$GOPATH/pkg/mod/
export GOBIN=$GOPATH/bin/
```

## 实际性能数据

笔者此前一直在改进用户界面和增加实现调用接口  
直到测试时, 并未对核心模板与重复过程调用做优化, 但它的性能目前已经处于准优秀水平  
目前已经发现了众多可改进之处, 性能有大幅增长空间, 敬请期待  

关于测试数据:

- AFI 本身"自缚一手": 尽管在同一文件夹进行索引, 但坦率地说, 仅 AFI 具有完备的文件管理器功能, 为显示元数据, 调用比其他服务器多, 页面体积和结构都比其他软件复杂, 并且只有 AFI 启用了 gzip(虽然是BestSpeed), 因此相较而言 AFI 在对比中比较吃亏且测试数据是不严谨的, 不能证明 "AFI 的性能是 Nginx 的 25%", 笔者提供这个数据仅仅是为了做除了 QPS 以外与其他服务器软件响应的性能参考(毕竟 QPS 和 CPU 性能与磁盘 IO 挂钩, 树莓派和SD卡上绝对跑不到下方的 QPS)  
- 测试的地址是 web 界面, 不是数据接口, 理论上数据接口是单一调用, 更快但不能进行对比实验  
- 您可用下方提供的命令在您的平台上获取测试数据 (请不要用它压力测试他人的网站!)  

```text
Test Platform: AMD Ryzen 3600X, tmpfs, 12 item with DESCRIPT.ION in directory
OS: glibc linux-zen 6.19.10
Date: 2026-04-02, 04-12
Version: latest
Command: wrk -t8 -c50 -d15s http://addr/
Test Address: /

QPS Performace from test:
Server   QPS Data    QPS Bar (higher is better)         Gzip     Version  Page
Nginx    60,242 QPS  ████████████████████████████████   Disabled 1.28.3   Default Index
Apache   34,207 QPS  █████████████████░░░░░░░░░░░░░░░   Disabled 2.4.66   Default Index
AFI      21,914 QPS  ███████████░░░░░░░░░░░░░░░░░░░░░  BestSpeed 26.4.26  Web Interface (without CSS & JS embedded in bench) (net/http)
AFI(old) 15,262 QPS  ████████░░░░░░░░░░░░░░░░░░░░░░░░  BestSpeed 26.4.3   Web Interface (without CSS & JS embedded in bench) (net/http)
PyPy      4,169 QPS  ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   Disabled 7.3.21   Default Index (http.server)
CPython   2,128 QPS  █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   Disabled 3.14.3   Default Index (http.server)

Latency from the same test:
Server     Average     Latency Bar (lower is better)      Maximum
Nginx       0.91ms     █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   14.49ms ▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
Apache      1.43ms     ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   41.05ms ▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
AFI 26.4.26 3.01ms     █████░░░░░░░░░░░░░░░░░░░░░░░░░░░   36.24ms ▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
AFI 26.4.3  4.69ms     █████░░░░░░░░░░░░░░░░░░░░░░░░░░░   67.67ms ▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
CPython    18.78ms     ████████████████████░░░░░░░░░░░░     1.67s ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓...
PyPy       23.86ms     ██████████████████████████░░░░░░     1.67s ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓...
Socket Errors from the same test:
Server   Number (lower is better)
Nginx      0
Apache     0
AFI        0
CPython    1
PyPy      11
```