Skip to content

从源码构建 ​

环境要求 ​

工具版本用途
Go1.24+编译服务端(SQLite 为纯 Go 驱动,可 CGO_ENABLED=0 交叉编译)
Node.js22构建前端 deploy-server-ui
pnpm最新版(corepack 启用即可)前端包管理
make任意Linux/macOS 构建入口
Git任意拉取源码;也是服务端运行期依赖

运行服务器只需要产出的二进制,不需要以上任何工具。

构建顺序:前端 → 拷贝 → Go ​

前端经 go:embed all:dist 打进二进制,所以顺序不可颠倒:

text
1. pnpm build          产出 deploy-server-ui/dist/
2. make ui / build.ps1 把 dist 拷进 deploy-server/internal/web/dist/
3. go build            编译,embed 目录里的内容成为二进制的一部分

拷贝步骤会剔除两类不该进生产的东西:*.map(source map,可占 dist 一半体积)与 *hot-update*(开发模式热更新产物),并校验 index.html 存在,缺了直接报错而不是打出一个空白页二进制。

Linux / macOS:Makefile ​

bash
cd deploy-server-ui
pnpm install && pnpm build

cd ../deploy-server
make ui                 # 仅拷贝前端产物(不会替你 pnpm build)
make build              # 本机二进制 bin/deploy-server
make linux              # 交叉编译 Linux/amd64 → bin/deploy-server-linux-amd64
make linux-arm64        # 交叉编译 Linux/arm64 → bin/deploy-server-linux-arm64
  • make all = ui + build;make run = build 后以回环地址本机起服务;
  • linux/linux-arm64 目标设置 CGO_ENABLED=0,产物无 libc 依赖, 扔到任意同架构 Linux 上就能跑;
  • 前端目录按候选路径自动探测,找不到时用 make ui UI_DIR=/path/to/deploy-server-ui 显式指定;
  • make docker 构建镜像(上下文自动切到仓库根),见 06。

Windows:scripts/build.ps1 ​

powershell
cd deploy-server-ui
pnpm.cmd install
pnpm.cmd build

cd ..\deploy-server
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build.ps1 -Local
参数作用
-Version <v>写入二进制的版本号(默认 0.1.0)
-Local额外产出 Windows 版 bin\deploy-server.exe 供本机调试
-SkipUI跳过「拷贝 dist 进 embed 目录」,仅前端没改动时使用
-UiDir <path>显式指定前端仓库位置

脚本默认产出 bin\deploy-server-linux-amd64(生产部署用)。两个坑:

  • 刚跑完 pnpm build 不要带 -SkipUI:带了它新前端不会被编进去, 二进制里还是上一次的旧 UI;
  • 脚本只能在 Windows 上跑(路径处理按 Windows 写,开头会拒绝其他 平台)。Linux/macOS 即使装了 pwsh 也请用 Makefile。

版本号注入 ​

版本通过 ldflags 写入 main.version,显示在 version 子命令、 /api/v1/healthz 与 doctor 里:

bash
go build -ldflags "-s -w -X main.version=1.2.3" -o bin/deploy-server ./cmd/server
# Makefile: make linux VERSION=1.2.3
# Docker:   docker build --build-arg VERSION=1.2.3 ...

不带 ldflags 直接 go build 时版本为 0.1.0-dev。

测试与检查 ​

bash
cd deploy-server
go test ./... -count=1     # 或 make test
make vet                   # go vet ./...
make fmt                   # gofmt -l -w .

集成测试会真跑「登录 → 建项目 → 执行 → 看日志 → Hook 触发 → 取消 → 权限隔离」整条主链路;中间件相关测试一律 dryRun,不会真的安装东西。

UI 占位页问题 ​

仓库里 internal/web/dist 放的是含 __PLACEHOLDER__ 标记的占位 index.html(保证空目录也能通过 go:embed 编译)。如果跳过前端构建直接 编译后端,二进制里就是这个占位页——访问站点只见提示、不见 UI。

排查与修复:

bash
# doctor 输出里 web.built=false 即命中此问题
curl -s http://127.0.0.1:10055/api/v1/system/doctor -H 'Authorization: Bearer <token>'
# 或 CLI:deploy doctor

# 修复:按正确顺序重建
cd deploy-server-ui && pnpm build
cd ../deploy-server && make ui && make linux

构建完成后按 05 systemd 部署与反向代理或 06 Docker 部署 上线;首次启动的初始化见初始化与登录。