用户文件服务器部署指南

本服务是一个轻量级文件上传/下载服务器，支持通过 API Key 认证进行文件管理，并提供 Web 管理后台。

---

1. 下载二进制文件

根据服务器 CPU 架构选择对应版本：

查看服务器架构：

uname -m
# x86_64  → 下载 amd64 版本
# aarch64 → 下载 arm64 版本

---

2. 上传到服务器

将下载好的二进制文件上传到服务器，例如上传到 /opt/file-server/ 目录：

# 创建目录
mkdir -p /opt/file-server
# 上传后添加执行权限
chmod +x /opt/file-server/user-file-manager-server-linux-amd64

---

3. 创建配置文件

在二进制文件同级目录下创建 config.yaml：

touch config.yaml

配置文件内容如下：

server:
  port: 8080
  server_id: "self-hosted"

auth:
  api_key: "your-secret-api-key-here"   # 必须修改，至少 16 位
  admin_username: "admin"               # 后台登录账号，留空则首次启动自动生成
  admin_password: ""                    # 后台登录密码，留空则首次启动自动生成

storage:
  upload_dir: "./uploads"               # 文件存储目录，相对路径或绝对路径均可

log:
  level: info                           # 日志级别：debug / info / warn / error

cors:
  allowed_origins: []                   # 允许跨域的前端域名，留空表示允许所有来源
  # 示例（限制特定域名）：
  # allowed_origins:
  #   - "https://your-frontend.com"

配置参数说明

---

4. 启动服务

前台运行（调试用）

./user-file-manager-server-linux-amd64
# ARM64 版本：
./user-file-manager-server-linux-arm64

首次启动若未配置账号密码，控制台会打印自动生成的凭据：

Admin credentials generated
Username: admin
Password: xK9mP2qR
Saved to config.yaml

请妥善保存，后续可在 config.yaml 中查看或修改。

后台运行（生产环境）

nohup ./user-file-manager-server-linux-amd64 > server.log 2>&1 &

查看运行日志：

tail -f server.log

停止服务：

# 查找进程 PID
ps aux | grep user-file-manager-server
# 停止
kill <PID>

然后就可以在指纹浏览器中窗口缓存设置->自定义服务器->添加上传地址url，ApiKey了

使用 systemd 管理（推荐）

创建服务文件 /etc/systemd/system/file-server.service：

[Unit]
Description=User File Manager Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/file-server
ExecStart=/opt/file-server/user-file-manager-server-linux-amd64
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable file-server
systemctl start file-server
systemctl status file-server

---

6. 后台管理

访问 Web 管理后台：

http://your_ip:8080/admin/login

使用 config.yaml 中配置的 admin_username / admin_password 登录。

后台功能：

• 查看已上传的文件列表
• 删除文件
• 查看磁盘使用情况

---

---

7. 常见问题

Q：启动报错 api_key must be at least 16 characters

config.yaml 中的 auth.api_key 长度不足 16 位，请修改为更长的密钥。

Q：上传返回 401

请求头中缺少 X-API-Key，或 Key 值与配置文件不一致。

Q：上传返回 400 invalid file type

当前只接受 .zip 格式文件。

Q：如何修改存储目录

修改 config.yaml 中的 storage.upload_dir，重启服务生效。支持相对路径（相对于二进制文件位置）和绝对路径。

Q：如何开启跨域支持

修改 cors.allowed_origins，填入前端域名，或留空允许所有来源：

cors:
  allowed_origins:
    - "https://your-frontend.com"