主题
从源码构建
环境要求
| 工具 | 版本 | 用途 |
|---|---|---|
| Go | 1.24+ | 编译服务端(SQLite 为纯 Go 驱动,可 CGO_ENABLED=0 交叉编译) |
| Node.js | 22 | 构建前端 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-arm64make 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 部署 上线;首次启动的初始化见初始化与登录。