goploader 1.0.2 Docker Compose 部署指南

目标：在装有 Docker 的服务器上以 Docker Compose 部署 goploader 1.0.2 文件分享服务，覆盖镜像构建、配置文件编写、启动、上传下载验证、数据持久化与日常运维命令。已在 Ubuntu 24.04 LTS（x86_64）+ Docker 29.9.2 + Docker Compose v5.6.1 环境实测通过（2026-10-30）。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
Docker：29.9.2（docker --version）
Docker Compose：v5.6.1（docker compose version）
软件版本：goploader 1.0.2（官方最新 Release，2026-10-30 查询）
服务器 IP：192.168.146.128（示例环境实际地址，下同）
端口规划：宿主机 8152 → 服务容器内 8080
数据目录：/opt/goploader/（compose 文件与数据目录同置）
goploader 无官方预构建镜像，本文按官方 Dockerfile 本地构建镜像 gpldr:v1.0.2

二、镜像选型说明

goploader 官方以「源码 + Dockerfile」的形态提供容器化支持，未在 Docker Hub 等公共仓库发布官方镜像，因此需要本地构建。官方仓库提供两条构建路径：

make docker：官方 Makefile 目标，执行 docker build -t gpldr:latest -t gpldr:v1.0.2 -f Dockerfile .，同时打 latest 与版本号两个标签；
直接 docker build：自选标签构建，本文采用该方式构建 gpldr:v1.0.2。

官方 Dockerfile 结构（两阶段构建，均 digest 固定，可复现）：

阶段	基础镜像	说明
builder	`golang:1.26-alpine`（digest 锁定）	安装 git，`go mod download` 校验依赖后以 `CGO_ENABLED=0` 构建静态二进制
final	`gcr.io/distroless/static`（digest 锁定）	仅拷入二进制；`VOLUME /data`、`WORKDIR /data`、`EXPOSE 8080`、`ENTRYPOINT /go/bin/gpldr`

final 阶段采用 distroless/static 意味着运行环境没有任何 shell 与调试工具，镜像攻击面最小、体积极小（本文实测构建产物约 42.5 MB）。

⚠️ 注意：官方 Dockerfile 两处 FROM 在受限网络下可能拉取失败。2026-10-30 实测本网络环境：

gcr.io 不可达，构建报错（节选）：failed to do request: Head "https://gcr.io/v2/distroless/static/manifests/sha256:28ef...": dial tcp 142.250.107.82:443: connect: connection refused；

Alpine 官方源 dl-cdn.alpinelinux.org 不可达，builder 阶段报错（节选）：WARNING: updating and opening https://dl-cdn.alpinelinux.org/alpine/v3.23/community/x86_64/APKINDEX.tar.gz: Connection refused。

可用降级改法（实测构建成功）：final 阶段基础镜像改用 gcr.m.daocloud.io/distroless/static@sha256:28efbe90d0b2f2a3ee465cc5b44f3f2cf5533514cf4d51447a977a5dc8e526d0（同 digest 的国内镜像代理）；builder 阶段 apk 源替换为清华镜像并指定国内 Go 模块代理，把依赖安装行改为：
ENV GOPROXY=https://goproxy.cn,direct
RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apk/repositories && apk update && apk add --no-cache git
若服务器 Docker 守护进程已配置 HTTP 代理或网络不受限，可保持官方 Dockerfile 原样。

三、前置条件

服务器已安装 Docker 与 Docker Compose 插件（验证回显见下）；
服务器 8152 端口未被占用，且防火墙放行（本文内网实测环境直接可达）；
服务器可访问 GitHub（拉取源码）与容器镜像仓库（拉取构建基础镜像）。

验证 Docker 环境：

docker --version
docker compose version

实测回显：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

四、部署步骤

4.1 创建目录与配置文件

goploader 的全部数据（配置、数据库、上传文件）都在一个工作目录内。创建目录并写入最小配置：

mkdir -p /opt/goploader/data && cd /opt/goploader

写入 data/conf.yml：

name_server: 192.168.146.128:8152
append_port: false
port: 8080
prometheus_enabled: true

配置项说明：

name_server：外界访问本服务所用的地址，服务端用它拼装返回给上传者的下载 URL，必填。此处宿主机对外地址是 8152 端口，因此写成 192.168.146.128:8152；
append_port：为 false 时返回 URL 直接使用 name_server 原文（地址里已带端口）；若 name_server 只写域名、端口要另拼，才设为 true；
port：服务进程实际监听端口，即容器内的 8080，与 compose 的容器内端口对应；
prometheus_enabled：开启 Prometheus 指标端点 /metrics（不需要可设为 false）。

其余未写出的参数（上传目录、大小限制等）走内置默认值，含义与完整清单见官方文档与《goploader 1.0.2 配置参数详解》。

4.2 获取源码并构建镜像

cd /opt/goploader
git clone -b v1.0.2 --depth 1 https://github.com/Depado/goploader.git src
cd src
docker build -t gpldr:v1.0.2 .

构建成功回显（节选尾部）：

#17 exporting to image
#17 exporting layers 0.6s done
#17 exporting manifest sha256:dd06034aa51b28e8617bb87972ba95f94fc13ffd5787e87f4889f94fd9fe6e71 done
#17 exporting config sha256:870d30f3b95bda35020e385a6c33b9fc1c9bf53490e1f586d337c7d18fba12d9 done
#17 naming to docker.io/library/gpldr:v1.0.2 done
#17 unpacking to docker.io/library/gpldr:v1.0.2 0.1s done
#17 DONE 0.7s

确认镜像已生成：

docker images gpldr

实测回显：

REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
gpldr        v1.0.2    b23c05f5846a   8 minutes ago    42.5MB

4.3 编写 docker-compose.yml

在 /opt/goploader/ 下创建 docker-compose.yml：

services:
  server:
    image: gpldr:v1.0.2
    container_name: goploader-server
    restart: unless-stopped
    ports:
      - "8152:8080"
    volumes:
      - ./data:/data

要点：

image 使用上一步构建的 gpldr:v1.0.2；
8152:8080：宿主机 8152 映射到容器内 8080（port 配置的监听端口）；
./data:/data：官方镜像工作目录为 /data，配置、数据库、上传文件全部落在该挂载目录下，实现持久化。

4.4 启动服务

cd /opt/goploader && docker compose up -d

实测回显：

 Network goploader-stack_default Creating
 Network goploader-stack_default Created
 Container goploader-server Creating
 Container goploader-server Created
 Container goploader-server Starting
 Container goploader-server Started

查看运行状态：

docker compose ps

实测回显：

NAME               IMAGE          COMMAND           SERVICE   CREATED         STATUS         PORTS
goploader-server   gpldr:v1.0.2   "/go/bin/gpldr"   server    2 seconds ago   Up 2 seconds   0.0.0.0:8152->8080/tcp, [::]:8152->8080/tcp

查看服务日志确认监听：

docker logs goploader-server

实测回显（节选）：

INFO |     server | 2026/10/30 - 08:38:26 |                 | Total   0 (0)
INFO |     server | 2026/10/30 - 08:38:26 |                 | Current 0 (0)
INFO | monitoring | 2026/10/30 - 08:38:26 |                 | Started Monitoring
INFO |     server | 2026/10/30 - 08:38:26 |                 | Started goploader server on port : 8080

4.5 上传下载验证

用 curl 上传一个文本文件（curl 访问首页还会先得到终端教程，见 4.6）：

echo "hello goploader 1.0.2 on ubuntu 22.04" > sample.txt
curl -F file=@sample.txt http://192.168.146.128:8152/

实测回显（201，URL 为 资源ID/加密密钥 两段）：

http://192.168.146.128:8152/v/gEtLee11z0/DjMxAR9R8eArmpt2

下载验证内容一致：

curl http://192.168.146.128:8152/v/gEtLee11z0/DjMxAR9R8eArmpt2

hello goploader 1.0.2 on ubuntu 22.04

查看响应头确认原始文件名随下载返回：

curl -I http://192.168.146.128:8152/v/gEtLee11z0/DjMxAR9R8eArmpt2

实测回显：

HTTP/1.1 200 OK
Content-Disposition: filename="sample.txt"
Date: Fri, 30 Oct 2026 08:39:12 GMT
Content-Length: 38
Content-Type: text/plain; charset=utf-8

4.6 各入口快速自检

检查项	命令	预期
终端教程页	`curl -s http://192.168.146.128:8152/`	输出 ASCII 使用教程文本
Web 首页	`curl -s -A "Mozilla/5.0" http://192.168.146.128:8152/`	`200`，HTML `<title>Goploader</title>`
移动端页面	`curl -s -o /dev/null -w "%{http_code}" -A "Mozilla/5.0" http://192.168.146.128:8152/simple`	`200`
指标端点	`curl -s -o /dev/null -w "%{http_code}" http://192.168.146.128:8152/metrics`	`200`（`prometheus_enabled: true` 时）

终端教程页实测输出（curl -s http://192.168.146.128:8152/）：

                   _      _        
                  | |    | |       
      ____  ____  | |  _ | |  ____ 
     / _  ||  _ \ | | / || | / ___)
    ( ( | || | | || |( (_| || |    
     \_|| || ||_/ |_| \____||_|    
    (_____||_|

Because file sharing is meant to be easy
 ~ Server-side encrypted file sharing ~

Usage

Upload from stdin
$ tree | curl -F file=@- http://192.168.146.128:8152
Simple file upload
$ curl -F file=@myfile.txt http://192.168.146.128:8152

五、数据持久化说明

goploader 在容器内的全部状态都收敛在 /data（compose 已挂载到宿主机 ./data）：

路径	内容	产生方式
`/data/conf.yml`	服务配置	部署时手工写入
`/data/goploader.db`	bbolt 单文件数据库（文件元数据：文件名、大小、有效期、once 标记）	首次启动自动创建
`/data/up/`	上传文件的加密存储目录	首次启动自动创建

部署完成后查看宿主机数据目录（实测）：

conf.yml  goploader.db  up

备份：直接打包 /opt/goploader/data/ 整目录即可（数据库为单文件，冷备份无一致性风险）；
清理：到期文件与 once 文件由服务端内置监控协程自动从磁盘与数据库删除，无需手工清理；
迁移：把 data 目录整体拷贝到新服务器、保持 conf.yml 中 name_server 正确即可恢复服务。

六、环境变量表

goploader 不提供环境变量配置入口：官方 Dockerfile 未定义任何可覆盖配置的环境变量，服务启动时只从工作目录读取 conf.yml（默认相对路径 conf.yml，可用 -c 指定）。因此无需（也无法）通过 environment: 注入配置，所有参数统一在 data/conf.yml 中维护，修改后 docker compose restart 生效。常用参数速查见下一节。

七、配置参数说明

键	默认值	说明
name_server	（必填）	外界访问地址，用于拼装返回 URL
port	8080	服务监听端口（容器内端口）
append_port	false	返回 URL 是否在 name_server 后追加端口
host	空	监听绑定地址，空为所有接口
size_limit	20	单文件大小上限（MB）
view_limit	5	代码高亮查看页的大小上限（MB），超限仍可下载
disk_quota	0	上传文件总占用上限（GB），0 为不限
uniuri_length	10	URL 中资源 ID 长度
key_length	16	加密密钥长度
token	空	非空时上传请求必须携带该 token，否则 `401`
loglevel	info	日志级别：debug / info / error / disabled
prometheus_enabled	false	是否暴露 `/metrics` 端点
upload_dir	up/	上传文件目录（相对工作目录）
db	goploader.db	数据库文件名

修改示例（把单文件上限调到 100 MB 并关闭指标）：

size_limit: 100
prometheus_enabled: false

docker compose restart

实测回显：

 Container goploader-server Started

参数完整语义、HTTPS、token、网页形态等配置的逐项详解见《goploader 1.0.2 配置参数详解》。

八、配置文件挂载

理解挂载机制可以避免「改了配置不生效」：

官方镜像 WORKDIR 为 /data，启动命令为 /go/bin/gpldr，不带参数时读取相对路径 conf.yml，即 /data/conf.yml；
compose 将宿主机 ./data 挂载到 /data，因此实际读取宿主机的 /opt/goploader/data/conf.yml；
修改宿主机该文件后执行 docker compose restart 即可生效（配置只在启动时读取一次）；
name_server 必须写「外界可达」的地址（域名 + 对外端口），与容器内 port 无关——本例容器内监听 8080、对外为 8152，因此 name_server: 192.168.146.128:8152。

九、等价 docker run

不使用 compose 时，等价的单命令部署（官方 README 原生命令即此形态）：

docker run -d --name=goploader-server \
  -v /opt/goploader/data:/data \
  -p 8152:8080 \
  --restart unless-stopped \
  gpldr:v1.0.2

与本文 compose 完全等价（数据目录、端口、重启策略一致）。

⚠️ 注意：镜像基于 distroless/static，没有任何 shell，无法 docker exec goploader-server sh 进入排查。实测报错：
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH
排障请依赖 docker logs 与宿主机 data 目录内的文件检查；确需进容器只可调用镜像内唯一的可执行文件（如 docker exec goploader-server /go/bin/gpldr -h 查看服务端参数）。

十、常用运维命令

docker compose ps                 # 查看运行状态
docker compose logs -f --tail 50  # 跟踪最近 50 行日志
docker compose restart            # 修改 conf.yml 后重启生效
docker compose down               # 停止并移除容器与网络（数据目录保留）
docker compose up -d              # 再次启动

docker compose logs -f --tail 20 实测回显（一次上传与下载的完整日志）：

INFO |     server | 2026/10/30 - 08:38:28 |      172.18.0.1 | GET /
INFO |     server | 2026/10/30 - 08:38:28 |      172.18.0.1 | Created HuhKSlrDfd - 38B
INFO |     server | 2026/10/30 - 08:38:28 |      172.18.0.1 | GET /simple
INFO |     server | 2026/10/30 - 08:39:12 |      172.18.0.1 | Created gEtLee11z0 - 38B
INFO |     server | 2026/10/30 - 08:39:15 | 192.168.146.128 | Fetched gEtLee11z0 - 38B

日志含义：Created 为上传成功（含资源 ID 与大小），Fetched 为下载发生，once 文件被读取后会追加 Deleted 日志。

升级版本流程：修改 compose 中 image 标签为新版本构建产物（如 gpldr:v1.0.3）→ 构建新镜像 → docker compose up -d。数据目录格式未变时可直接复用；升级前建议先打包备份 data/ 目录。

十一、常见问题

Q1：构建时报 gcr.io 或 dl-cdn.alpinelinux.org 连接失败？

受限网络下的已知现象（真实报错见「二、镜像选型说明」⚠️ 注记）。按该节给出的两行改法替换 final 阶段基础镜像源与 apk 源、指定 GOPROXY=https://goproxy.cn,direct 后实测构建成功；守护进程配置了代理的环境可保持官方文件原样。

Q2：上传返回 413 Entity is too large (Max : 20 MB)？

单文件超过 size_limit（默认 20 MB）。实测 21 MB 文件被拒、38 B 文件正常。调大 conf.yml 中 size_limit 后 docker compose restart 生效（实测设为 1 时回显变为 Max : 1 MB，确认即时生效）。

Q3：上传返回 401 Incorrect token？

服务端 conf.yml 设置了 token，请求未携带或携带错误。curl 上传需附加表单字段 -F token=<服务端token>；官方客户端则在 ~/.config/goploader.conf.yml 中配置 token 后自动携带。

Q4：一次性链接第二次访问返回 404？

once 上传的文件在第一次成功下载后即从磁盘与数据库删除（实测首次 200、二次 404），这是预期行为而非故障；日志中可看到对应的 Deleted 记录。

Q5：/metrics 返回 404？

prometheus_enabled: false（或未写）时不注册该路由（实测关闭时 404、开启后 200）。需要接入 Prometheus 时在 conf.yml 设 prometheus_enabled: true 并重启。指标名为 gpldr_uploaded_files_total（按来源 IP 计数）与 gpldr_uploaded_files_size_total（上传字节累计）。

Q6：修改了 conf.yml 但行为没变？

配置仅在启动时读取。确认修改的是宿主机 /opt/goploader/data/conf.yml（而非容器内其他路径），然后 docker compose restart。

十二、参考链接

goploader 官方仓库：https://github.com/Depado/goploader
官方 Docker 部署说明（README「Docker image」节）：https://github.com/Depado/goploader#docker-image
goploader 服务端文档：https://depado.github.io/goploader/server/serve.html
distroless/static 镜像说明：https://github.com/GoogleContainerTools/distroless