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

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

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

特色:  

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

## 安全与不安全设计

考虑到此程序可能被使用的场景与便于方案选型, 笔者必须指出此程序存在的问题  
如您发现了其他可能的漏洞, 请在 issues 指出, 若属实, 笔者会将其修复或加入下方列表  

安全建议:

- 强烈建议配置一个 nginx 反向代理
  - 必要时设置超时, 限制请求大小与频率
- 完全避免使用 HTTP
- 必要时设置磁盘配额

- 安全设计:
  - 可防止路径穿越攻击
  - 有基本的权限管理系统 (基于 HTTP Basic Authication)
- 不安全设计:
  - 不能完全防范的攻击
    - XSS (不可防范)
    - Timing Attack (不可防范, 但可通过设置较复杂的用户名规避)
  - 能防范的攻击
    - symlink 逃逸攻击 (可选且默认开启, 但开启后您就不能使用 linux 的符号链接便利了)
    - 路径穿越攻击
    - CSRF (HTTP Basic Authication 天然防范)
  - 其他不安全设计:
    - 密码以明文形式传输 (因此千万不要在非 HTTPS 环境公网部署或预留 HTTP 访问, 除非您完全不配置用户(相当于原版 Gossa 的只读模式))
    - 后端密码参数化 (可登录服务器后用 ps 或类似工具查看)
    - 日志可能泄漏敏感信息 (可以通过修改源代码编译解决, 但我们提供的二进制释出没有移除敏感信息输出)
    - DoS 攻击 - 我们认为这件事应该由 nginx 反向代理预防
    - 请求大小无限制导致的超大文件占用和可能导致的 OOM 崩溃 - 我们认为这件事应该由 nginx 反向代理或磁盘配额限制预防, 并且就事实而言, 这很大程度上是有权限的用户行为不当引起的问题
    - 外部字体 Referer 泄露 (仅会得知您访问的链接, 但如果您需要, 可以移除前端中引用的在线字体链接) 就事实而言, 外部字体提供商没有收集这种数据的动机, 但如果您在内网部署, 则您可能不希望任何外部服务知道内网的文件结构
    - 无自带的响应超时: 可能招致 Slowloris 服务瘫痪 - 但这可由 nginx 反向代理预防
    - 权限提升风险: AFI 以什么用户运行, 就有什么权限 -- 如果以 root 运行且将分享目录设置为根目录, 则任何登录用户都能删除系统
  - 未对特定安全需求进行的设计:
    - 不支持细粒度权限控制 (我们支持配置多个用户, 但登录后您就只能是对分享目录下的文件完全可写(取决于运行 afi 的用户)的状态了)
    - 没有自带的防暴力破解机制
    - 没有操作审计日志
    - 没有密码哈希存储 (后端明文比较)
- 可能被误解为是不恰当的设计
  - 代码中不恰当的注释, 但这些注释(html, js 和 css 中的)事实上会被 go 的模板系统清除(即使有 "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 性能挂钩, 树莓派上绝对跑不到下方的 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
Version: latest
Command: wrk -t8 -c50 -d15s http://addr/
Test Address: /

QPS Performace from test:
Server   QPS Data    QPS Bar (higher is better)         Gzip     Page
Nginx    60,242 QPS  ████████████████████████████████   Disabled Default Index
Apache   34,207 QPS  █████████████████░░░░░░░░░░░░░░░   Disabled Default Index
AFI      15,262 QPS  ████████░░░░░░░░░░░░░░░░░░░░░░░░  BestSpeed Full-functional web file manager (without CSS & JS embeded in bench) (net/http)
PyPy      4,169 QPS  ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   Disabled Default Index (http.server)
CPython   2,128 QPS  █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   Disabled 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       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
```