goploader 1.0.2 配置参数详解

目标：逐项讲清 goploader 1.0.2 服务端配置文件 conf.yml 的全部参数——默认值、作用、修改方式与生效验证，并给出可直接套用的生产配置模板。本文所有演示均在 Ubuntu 24.04 LTS（x86_64）上以官方 Release 服务端二进制（goploader 1.0.2）实测通过（2026-10-30）。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
软件版本：goploader 1.0.2（官方 Release 服务端二进制 goploader-server）
服务工作目录：/opt/goploader/（内含 conf.yml、goploader-server、goploader.db、up/）
服务监听端口：8153（本文演示实例）
服务器地址：192.168.146.128（示例环境实际地址，下同）
参数依据：官方文档 conf.yml 说明页 + 官方仓库 1.0.2 源码（server/conf/conf.go）双重核对

二、前置条件

已按官方 Release 包或源码方式部署好 goploader 1.0.2 服务端，且服务可正常启动（最小部署流程见官方文档）；
拥有对服务工作目录与 conf.yml 的写权限；
修改配置后可重启服务进程（systemd 托管环境用 systemctl restart，手动运行为重新执行启动命令）。

goploader 的参数只有一个入口：conf.yml。它不支持环境变量覆盖，也没有子命令式的 config get/set，所有调参都是「改文件 → 重启进程」。

三、参数查看与修改方式

3.1 查看当前配置

配置文件就在服务工作目录下（默认文件名 conf.yml，与二进制同目录；启动时可用 -c 指定其他路径）：

cat /opt/goploader/conf.yml

本文演示实例的配置（实测）：

name_server: 192.168.146.128:8153
port: 8153
prometheus_enabled: true

未写出的键按内置默认值生效（name_server 除外，它是唯一必填项）。

3.2 交互式初始配置向导

服务端还提供一次性 Web 向导生成 conf.yml，首次部署时在二进制所在目录执行：

./goploader-server -i

实测回显：

Please go to http://127.0.0.1:8080 to setup goploader.

向导页面实测可访问（HTTP 200，页面标题 Goploader），在表单中填完参数提交后会在当前目录生成 conf.yml。

⚠️ 注意：官方文档（install 页）写向导运行在 8008 端口，但 1.0.2 实测监听 8080（源码 server/setup/setup.go 固定 r.Run(":8080")）。若 8080 被占用向导无法启动，先腾出端口。

3.3 修改与生效验证

编辑 conf.yml 后重启服务进程生效（配置只在启动时读取一次）。验证「修改已生效」最直接的方法是选一个有外部表现的参数做边界验证，例如把 size_limit 改为 1 后上传 2 MB 文件：

size_limit: 1

curl -F file=@demo2m.bin http://192.168.146.128:8153/

实测回显（限制值已从默认 20 变为 1，证明重启后生效）：

Entity is too large (Max : 1 MB)

验证完成后改回 size_limit: 20 并重启即恢复默认行为。

四、参数总览

下表为 1.0.2 全部配置键。默认值取自源码 server/conf/conf.go 的 NewDefault()/FillDefaults() 与官方文档 install 页（两者不一致处已标注）。

键	类型	默认值	作用
name_server	string	（必填）	外界访问地址，拼装返回给上传者的 URL
host	string	空	监听绑定地址，空为所有接口
port	int	8080	服务监听端口
append_port	bool	false	返回 URL 是否在 name_server 后追加 `:port`
token	string	空	上传口令，非空时上传请求必须携带
serve_https	bool	false	由 goploader 自身提供 HTTPS
ssl_cert	string	空	证书路径（serve_https 为 true 时必填）
ssl_private_key	string	空	私钥路径（serve_https 为 true 时必填）
upload_dir	string	up/	上传文件存储目录（相对工作目录或绝对路径）
db	string	goploader.db	bbolt 数据库文件路径（单文件）
uniuri_length	int	10	URL 中资源 ID 的长度
key_length	int	16	AES 加密密钥长度
size_limit	int	20	单文件大小上限（MB）
view_limit	int	5	代码高亮查看页的大小上限（MB）⚠️ 官方文档未收录此键，1.0.2 代码新增
disk_quota	float	0	上传文件总占用上限（GB），0 为不限
loglevel	string	info	日志级别：debug / info / error / disabled
stats	bool	false	首页展示文件总数与总大小统计
sensitive_mode	bool	false	敏感模式：网页只保留上传表单，隐藏项目信息
no_web	bool	false	完全禁用网页界面，仅保留 curl/客户端 API
fulldoc	bool	见 5.4 说明	首页是否展示完整使用文档区块
always_download	bool	false	下载响应强制为附件下载而非浏览器内联预览
disable_encryption	bool	false	关闭服务端加密（写盘更快，URL 不再含 key 段）
prometheus_enabled	bool	false	暴露 Prometheus 指标端点 `/metrics`

💡 说明：布尔键在 conf.yml 未写出时一律按 false 处理。fulldoc 官方文档标注默认 true，但 1.0.2 代码内置零值为 false 且默认值填充不覆盖布尔零值——要展示首页文档区块时显式写出 fulldoc: true 最稳妥。

五、核心参数分类详解

5.1 服务地址与端口（name_server / host / port / append_port）

name_server 是最关键也最容易配错的参数：它不参与实际监听，只决定返回给上传者的下载 URL 长什么样。本文实例 name_server: 192.168.146.128:8153，上传返回（实测）：

http://192.168.146.128:8153/v/w2Am18J9JJ/3xlEKzJDh1z7rhCj

host/port 决定真实监听。默认 host 为空（绑定所有接口）、port: 8080；
append_port: false（默认）时 URL 直接使用 name_server 原文；只有当 name_server 只写域名而访问端口又与 80 不同（如 example.com 实际走 8003）时，才设 true 由服务端自动补 :port；
典型组合：域名 + 反向代理终结 TLS 到本机 8080 → name_server: files.example.com、append_port: false、port: 8080；
若配错（如写了内网另一台机器的地址），服务本身照常工作，但所有返回的链接都无法访问——排障时先核对 name_server。

5.2 上传与存储（upload_dir / db / size_limit / view_limit / disk_quota / uniuri_length / key_length）

upload_dir（默认 up/）：文件加密后的落盘目录，不存在时启动会自动创建；
db（默认 goploader.db）：bbolt 单文件数据库，存文件名、大小、有效期、once 标记等元数据；
size_limit（默认 20，单位 MB）：单文件上限，超出返回 413。实测超限回显：

Entity is too large (Max : 1 MB)

view_limit（默认 5，单位 MB）：只约束代码高亮查看页。实测上传 6 MB 文件后：/v/<ID>/<key>/go 高亮页返回 403，而同一下载 URL 仍是 200 可正常下载——它不是「最多可下载 5 次」也不是下载大小上限；
disk_quota（默认 0，单位 GB）：上传文件总占用上限，0 为不限；超配额的上传返回 400 Insufficient disk space. Try again later.；
uniuri_length（默认 10）与 key_length（默认 16）：前者是 URL 中资源 ID 长度（防猜测遍历），后者是 AES 密钥长度（16 字节随机串，直接拼在 URL 中）。两者越长安全性越高、URL 越长；调整只影响新上传的文件。

5.3 安全与隐私（token / sensitive_mode / serve_https / ssl_cert / ssl_private_key）

token：为空时任何人可上传；设为非空后，上传请求必须带 token 表单字段。实测三种情况：
```
# 未携带 token
curl -F file=@sample.txt http://192.168.146.128:8153/
```
```
Incorrect token
```
```
# 错误 token
curl -F token=badpass -F file=@sample.txt http://192.168.146.128:8153/
```
```
Incorrect token
```
两者均返回 401；携带正确 token（-F token=q1w2e3r4）则正常返回 201 与下载 URL。注意客户端需在 ~/.config/goploader.conf.yml 的 token 键中配置同一口令才会自动携带。
sensitive_mode: true：网页界面只保留上传表单，隐藏项目名、页脚、统计等一切信息（官方文档明确该模式会覆盖 fulldoc 与 stats 的展示效果），适合不想暴露所用软件的场景；
serve_https + ssl_cert + ssl_private_key：由 goploader 直接对外提供 HTTPS（证书自备）；更常见的做法是保持 HTTP、由反向代理终结 TLS，此时三个键保持默认。

5.4 网页与统计（no_web / fulldoc / stats）

no_web: true：彻底关闭 HTML 页面（首页、移动端页、高亮查看页），只保留 curl/客户端上传与 /v/... 下载，适合纯 API 用途；
fulldoc：控制首页是否渲染完整使用文档区块（源码模板中 {{ if .fulldoc }} 控制）。见「参数总览」下方说明——建议显式配置；
stats: true：首页展示已上传文件总数与总大小。注意官方文档特别说明：即使设为 false，统计仍在后台收集，只是不展示。

5.5 加密与观测（disable_encryption / prometheus_enabled / loglevel）

disable_encryption: true：跳过 AES-CTR 落盘加密，写盘更快；代价是 URL 不再含 key 段（路由变为 /v/<资源ID> 两段形态），服务端以明文保存文件；
prometheus_enabled: true：暴露 /metrics。实测指标（两次 38 B 文件上传后）：

# HELP gpldr_uploaded_files_size_total Size of uploaded files
# TYPE gpldr_uploaded_files_size_total counter
gpldr_uploaded_files_size_total 76
# HELP gpldr_uploaded_files_total Count of files uploaded
# TYPE gpldr_uploaded_files_total counter
gpldr_uploaded_files_total{ip="127.0.0.1"} 2

ip 标签记录上传请求来源 IP（本例上传方与服务同机，故为 127.0.0.1）。该键为 false 时路由不注册，访问 /metrics 返回 404（实测）：

metrics_off=404

loglevel：debug / info / error / disabled 四档，默认 info（兼顾可读与信息量）。info 下每次上传/下载都会输出 Created/Fetched 资源 ID 与大小；排障期临时切 debug，生产长期运行用 info 或 error。

5.6 下载行为（always_download）

默认 false 时，下载响应带 Content-Disposition: filename="sample.txt"（实测回显），文本类文件可在浏览器内联预览；设为 true 后响应改为 Content-Type: application/octet-stream + attachment，浏览器一律弹下载框，适合二进制为主的场景。

六、生产配置模板

适用场景：内网团队（约 50 人）的文件/日志投递点，4 核 8 GB 内存、SSD 磁盘 500 GB、域名走反向代理终结 HTTPS。goploader 为单进程 Go 服务，常驻内存约几十 MB，资源占用极小，参数重点在限额与安全：

# 对外地址：反代域名，HTTPS 由反代终结
name_server: files.example.com
append_port: false
# 反代回源端口
port: 8080

# 限额：单文件 100MB，总占用 50GB（0 为不限）
size_limit: 100
view_limit: 5
disk_quota: 50

# 上传口令：团队内分发，客户端 conf 中配置同一 token
token: q1w2e3r4

# 网页形态：保留完整界面与统计
fulldoc: true
stats: true
sensitive_mode: false

# 观测与日志
prometheus_enabled: true
loglevel: info

# 以下保持默认（显式写出便于审计）
upload_dir: up/
db: goploader.db
uniuri_length: 10
key_length: 16
always_download: false
disable_encryption: false
no_web: false

说明：

disk_quota: 50 防止匿名/失控上传写满磁盘，是共享服务最重要的保险丝；
token 阻止团队外人员上传（下载仍然公开，符合投递点定位）；
需要更隐蔽的部署时把 sensitive_mode 改为 true，网页只留下传表单。

七、常见问题

Q1：上传返回 401 Incorrect token 但我根本没设 token？

token 校验先于文件体读取。若 token 与 size_limit 同时配置，超大文件会把请求体截断，导致 token 字段解析失败，同样报 401 而非 413（实测：size_limit=1 + token 同开时上传 2 MB 文件返回 Incorrect token）。此时先核对请求是否带了正确 token，再核对文件大小。

Q2：上传返回 400 Invalid duration？

duration 字段只接受 30m / 1h / 6h / 1d / 1w 五个档位（实测传 2h 被拒）。curl 需显式带 -F duration=30m；不传默认 1d。

Q3：/metrics 返回 404？

prometheus_enabled 未开启（默认 false 时不注册该路由）。设 true 重启后实测恢复 200。

Q4：view_limit 和 size_limit 有什么区别？

size_limit 管上传（超限 413），view_limit 只管代码高亮查看页（超限 403，但仍可走下载 URL 正常下载，实测 6 MB 文件即此表现）。

Q5：配置改了但没生效？

配置只在进程启动时读取。确认改动落盘后重启服务进程（systemd 托管用 systemctl restart goploader，手动运行为结束进程后重新启动），再用「三、参数查看与修改方式」的边界法验证。

Q6：fulldoc 不配置时首页为什么不显示使用说明？

见「四、参数总览」说明：官方文档标注默认 true，但 1.0.2 代码内置零值为 false。需要展示时在 conf.yml 显式写出 fulldoc: true。

八、参考链接

官方 conf.yml 参数说明：https://depado.github.io/goploader/server/install.html
官方仓库（conf 源码：server/conf/conf.go）：https://github.com/Depado/goploader
goploader 服务端运行说明（systemd/supervisor）：https://depado.github.io/goploader/server/running.html
本文参数核对基准与实测日期：2026-10-30（goploader 1.0.2）