fan-files-build

补充说明

本教程介绍 fan-files 从源码编译、发布 GitHub Release 到目标服务器一键安装、卸载、升级的完整流程，适用于个人文件管理器自建发布链路。

项目：fan-files｜文件管理器 仓库：https://github.com/meimolihan/fan-files 编译发布主机：fnOS（Debian，本机 Go/Node/make 环境齐全） 部署测试主机：Debian Linux（amd64/arm64）

重要规则

1. GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag。
2. install.sh 使用 releases/latest/download，脚本不需要硬编码版本号。
3. 编译机器 ≠ 业务运行机器；fnOS 只做编译发布，业务跑在目标主机。
4. 编译默认 CGO_ENABLED=0 产出静态二进制；供 install.sh 远程下载使用。

一、编译发布机（fnOS）环境准备

1.1 安装依赖

apt update
apt install git curl build-essential

Go（本机 /usr/local/go/bin/go，确保 go version 正常），Node.js 20+，Make、pnpm。

1.2 安装 gh 命令行工具并授权 GitHub

gh auth login

选择 GitHub.com → SSH → 网页授权登录，务必勾选 repo 权限。

校验授权结果

gh auth status

输出必须包含：Token scopes: admin:public_key, gist, read:org, repo

1.3 拉取源码

git clone git@github.com:meimolihan/fan-files.git
cd fan-files
go mod download

项目目录结构

fan-files/
├── scripts/install.sh            # 远程一键安装脚本
├── scripts/uninstall.sh          # 卸载脚本
├── scripts/fan-files_backup.sh   # 备份脚本
├── scripts/fan-files_recover.sh  # 恢复脚本
├── scripts/build-and-push.sh     # 构建+打tag+推送脚本
├── frontend/                     # 前端（Vue + Vite）
├── http/                         # 后端 HTTP 处理
├── files/                        # 文件系统核心（MultiFs）
├── settings/                     # 配置管理
├── cmd/                          # CLI 入口
└── version/                      # 版本信息

二、配置一键安装脚本

确认 scripts/install.sh 头部常量（无需改动，默认已正确定义）：

APP_NAME="fan-files"
DEFAULT_PORT=8678
DEFAULT_DATA_DIR="/var/lib/fan-files"
DEFAULT_ROOT="/vol1/1000"

提交推送至 main 分支

git add scripts/install.sh
git commit -m "chore: update install script"
git push origin main

三、构建与发布

3.1 构建前端

cd frontend
pnpm install
CI=true pnpm run build

3.2 构建后端（静态二进制，供 install.sh 远程下载）

export VERSION=1.0.1
rm -rf bin && mkdir -p bin
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
  -ldflags="-s -w -X 'github.com/meimolihan/fan-files/version.Version=${VERSION}' -X 'github.com/meimolihan/fan-files/version.CommitSHA=$(git rev-parse HEAD)'" \
  -o bin/fan-files_linux_amd64 .

CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build \
  -ldflags="-s -w -X 'github.com/meimolihan/fan-files/version.Version=${VERSION}' -X 'github.com/meimolihan/fan-files/version.CommitSHA=$(git rev-parse HEAD)'" \
  -o bin/fan-files_linux_arm64 .

ls bin

3.3 一键发布（推荐，使用 build-and-push.sh）

./scripts/build-and-push.sh 1.0.1 --yes

内部流程：校验版本号 → 升版 version/version.go 与 frontend/package.json → 前端 pnpm run build → 后端 go build（含 Version+CommitSHA）→ git commit + git tag v1.0.1 → git push origin main + git push origin v1.0.1 → gh release create 上传 bin/fan-files_linux_amd64。

3.4 创建 GitHub Release 并上传二进制（手动备选）

VERSION=1.0.1
gh release create "v${VERSION}" \
  bin/fan-files_linux_amd64 \
  bin/fan-files_linux_arm64 \
  --title "v${VERSION}" \
  --notes "fan-files - File Manager"

校验 Release

访问：https://github.com/meimolihan/fan-files/releases/tag/v1.0.1

1. 状态：Published，不是 Draft 草稿
2. Assets 内必须存在两个编译二进制（fan-files_linux_amd64、fan-files_linux_arm64），不要只看源码 zip/tar.gz。

测试下载链接有效性

curl -I https://github.com/meimolihan/fan-files/releases/latest/download/fan-files_linux_amd64

返回 302 Found 正常；返回 404 代表附件缺失。

四、目标服务器远程一键安装

目标服务器需要 root 权限，已安装 curl。

4.1 预检查国内网络

curl -sSL https://raw.githubusercontent.com/meimolihan/fan-files/main/scripts/install.sh

输出 shell 脚本内容 = 网络正常；卡住超时需要网络代理。

4.2 执行一键安装

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-files/main/scripts/install.sh)"

交互步骤：

1. Enter listen port [default: 8678]: 回车使用默认，或填写自定义端口
2. Enter data directory [default: /var/lib/fan-files]: 回车使用默认路径
3. Enter root directory [default: /vol1/1000]: 回车使用默认主存储根
4. 脚本自动下载二进制（或使用本地 -b 产物）、创建 systemd 服务、启动程序
5. 输出 Web 访问地址；首次登录默认密码见启动日志

静默安装

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-files/main/scripts/install.sh)" \
  -p 8678 -d /var/lib/fan-files -r /vol1/1000 \
  --extra-root "存储空间2=/vol2/1000" -y

部署后运维命令

systemctl status fan-files
journalctl -u fan-files -f
systemctl restart fan-files
/usr/local/bin/fan-files -version

访问示例：http://10.10.10.251:8678

• 账号：admin
• 密码：首次启动日志输出，登录后必须修改密码

五、一键卸载

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-files/main/scripts/uninstall.sh)"

交互：

• Remove data directory /var/lib/fan-files ? [y/N]: 选择 y 删除数据（--purge），N 保留（--keep-data）

卸载完成：systemd 服务移除、二进制文件删除。

六、新版本发布两种模式

模式 1：递增新版本（正式环境，推荐）

不要复用旧 tag，版本号向上迭代，例如 v1.0.1 → v1.0.2

cd /vol1/1000/compose/opencode/workspace/filebrowser
./scripts/build-and-push.sh 1.0.2 --yes

目标服务器升级，直接重跑安装脚本，自动拉取 latest，覆盖二进制，systemd 自动重启

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-files/main/scripts/install.sh)"
/usr/local/bin/fan-files -version

模式 2：删除重建同名 Release（仅限内测，无线上用户）

⚠️ 已有服务器依赖该版本绝对禁止执行，会造成旧版本下载 404。

cd /vol1/1000/compose/opencode/workspace/filebrowser
# 删除github release
gh release delete v1.0.1 --yes
# 删除本地与远端git tag
git tag -d v1.0.1
git push origin --delete v1.0.1

# 重新编译并重建release上传附件
export VERSION=1.0.1
rm -rf bin && mkdir -p bin
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -X 'github.com/meimolihan/fan-files/version.Version=${VERSION}' -X 'github.com/meimolihan/fan-files/version.CommitSHA=$(git rev-parse HEAD)'" -o bin/fan-files_linux_amd64 .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w -X 'github.com/meimolihan/fan-files/version.Version=${VERSION}' -X 'github.com/meimolihan/fan-files/version.CommitSHA=$(git rev-parse HEAD)'" -o bin/fan-files_linux_arm64 .

gh release create "v${VERSION}" \
  bin/fan-files_linux_amd64 \
  bin/fan-files_linux_arm64 \
  --title "v${VERSION}" \
  --notes "fan-files - File Manager"

七、故障排查表

八、前端 UI 修改流程

前端为 Vue + Vite（frontend/），构建产物由后端静态文件服务提供：

1. 修改 frontend/src/ 前端代码
2. 重新构建：cd frontend && CI=true pnpm run build
3. 重新走发布流程：提交代码 → 构建 → 创建 Release
4. 目标服务器重跑一键安装脚本升级生效。

九、极简速查复制块

发布新版本速记

cd /vol1/1000/compose/opencode/workspace/filebrowser
./scripts/build-and-push.sh 1.0.2 --yes    # 或分步：
# cd frontend && pnpm install && CI=true pnpm run build
# export PATH=$PATH:/usr/local/go/bin
# CGO_ENABLED=0 go build -ldflags="-s -w -X 'github.com/meimolihan/fan-files/version.Version=1.0.2' -X 'github.com/meimolihan/fan-files/version.CommitSHA=$(git rev-parse HEAD)'" -o fan-files .
# git add . && git commit -m "release v1.0.2"
# git push origin main && git push origin v1.0.2

export VERSION=1.0.2
rm -rf bin && mkdir -p bin
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -X 'github.com/meimolihan/fan-files/version.Version=${VERSION}' -X 'github.com/meimolihan/fan-files/version.CommitSHA=$(git rev-parse HEAD)'" -o bin/fan-files_linux_amd64 .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w -X 'github.com/meimolihan/fan-files/version.Version=${VERSION}' -X 'github.com/meimolihan/fan-files/version.CommitSHA=$(git rev-parse HEAD)'" -o bin/fan-files_linux_arm64 .
gh release create "v${VERSION}" bin/fan-files_linux_amd64 bin/fan-files_linux_arm64 --title "v${VERSION}" --notes "更新说明"