开发环境搭建
May 22, 2026 · View on GitHub
阅读本文后，你将拥有一套完整的 HotPlex 开发环境，能够构建、测试和运行网关。
概述
HotPlex Gateway 基于 Go 1.26 构建，使用 Make 作为构建入口，依赖 golangci-lint 做代码质量检查。开发环境搭建分为三个阶段：工具链安装、项目初始化、开发服务启动。
前提条件
必需工具
| 工具 | 最低版本 | 安装方式 |
|---|---|---|
| Go | 1.26+ | go.dev/dl 或 brew install go |
| golangci-lint | v1.64+ | brew install golangci-lint 或 go install github.com/golangci-lint/golangci-lint/cmd/golangci-lint@latest |
| goimports | latest | go install golang.org/x/tools/cmd/goimports@latest |
| make | any | macOS 自带 / Linux apt install build-essential |
| git | 2.30+ | 系统包管理器 |
可选工具
| 工具 | 用途 | 安装方式 |
|---|---|---|
| Node.js / pnpm | WebChat 前端开发 | npm install -g pnpm |
| gh | PR 创建、Issue 管理 | brew install gh |
| SQLite3 | 数据库调试 | brew install sqlite |
| delve | Go 调试器 | go install github.com/go-delve/delve/cmd/dlv@latest |
验证工具链
make check-tools
输出应显示：
✓ Go
✓ golangci-lint
✓ goimports
步骤
1. 克隆仓库
Admin（有仓库权限）：
git clone git@github.com:hrygo/hotplex.git
cd hotplex
外部贡献者：
# 先在 GitHub 上 fork 仓库
git clone https://github.com/<your-username>/hotplex.git
cd hotplex
git remote add upstream https://github.com/hrygo/hotplex.git
2. 安装 Git Hooks
项目提供 pre-push hook，推送前自动运行格式化、lint、构建和测试：
make hooks
hook 流程：fmt → lint → vet → mod verify → build → test。
3. 配置环境变量
cp configs/env.example .env
必填项（开发阶段至少需要）：
# Admin API Token
HOTPLEX_ADMIN_TOKEN_1=$(openssl rand -base64 32 | tr -d '/+=' | head -c 43)
消息平台（按需配置）：
- Slack：
HOTPLEX_MESSAGING_SLACK_BOT_TOKEN、HOTPLEX_MESSAGING_SLACK_APP_TOKEN - 飞书：
HOTPLEX_MESSAGING_FEISHU_APP_ID、HOTPLEX_MESSAGING_FEISHU_APP_SECRET
不配置消息平台也能启动网关，WebSocket 和 Web Chat 功能独立可用。
4. 一键初始化
make quickstart
此命令依次执行 hooks → check-tools → build → test-short。成功后输出：
✓ Developer setup complete
make dev Start dev environment
make run Run gateway
make help Show all commands
5. 启动开发环境
make dev
启动两个服务：
| 服务 | 地址 | 说明 |
|---|---|---|
| Gateway | localhost:8888 | WebSocket 网关（使用 configs/config-dev.yaml） |
| Webchat | localhost:3000 | Web Chat UI（需要 pnpm） |
Webchat 首次启动会自动构建 Next.js 并嵌入 Go 二进制（
make webchat-embed）。如果跳过前端开发，只启动网关即可：make gateway-start。
验证
确认服务运行
make dev-status
运行完整 CI 流程
make check
如果输出 ✓ CI check passed，开发环境搭建完成。
查看日志
make dev-logs # 所有服务日志
make gateway-logs # 仅网关日志
日志文件位于 ./logs/hotplex.log，使用 JSON 格式（log/slog）。
开发工作流
日常循环
# 1. 编辑代码
# 2. 快速测试
make test-short
# 3. 提交前完整检查（等同于 CI）
make check
make check 执行流水线：fmt → lint → test → build。
命令速查
# 构建
make build # 构建网关二进制（输出到 bin/）
make run # 构建并前台运行
make clean # 清理构建产物
# 测试
make test # 完整测试（含 -race，15 分钟超时）
make test-short # 快速测试（-short，5 分钟超时）
make coverage # 生成覆盖率报告
# 质量
make fmt # go fmt + goimports
make lint # golangci-lint 检查
make quality # fmt + lint + test
make check # quality + build（CI 等价）
# 开发环境
make dev-start # 启动所有服务（推荐使用 make dev）
make dev-stop # 停止所有服务
make dev-reset # 停止并重启
make dev-status # 查看运行状态
运行特定测试
# 单个包
go test -race -run TestSessionTransition ./internal/session/...
# 带 verbose 输出
go test -race -v -run TestDeriveSessionKey ./internal/session/...
查看实时日志
tail -f logs/hotplex.log | jq .
# 过滤特定 session
cat logs/hotplex.log | jq 'select(.session_id == "xxx")'
IDE 配置
VS Code
安装扩展：
- Go（golang.go）— 代码补全、跳转、调试
推荐 settings.json：
{
"go.useLanguageServer": true,
"go.lintTool": "golangci-lint",
"go.lintOnSave": "package",
"go.testFlags": ["-race"],
"go.testTimeout": "120s",
"[go]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "golang.go"
},
"go.formatTool": "goimports",
"go.goimportsLocalPrefix": "github.com/hrygo/hotplex"
}
GoLand
- 启用 Go module 支持（Settings → Go → Go Modules）
- 配置 File Watcher 运行
goimportson save - 测试配置中勾选 Run with race detector
调试 Gateway
# 方式 1：使用 delve
dlv debug ./cmd/hotplex -- gateway start -c configs/config-dev.yaml
# 方式 2：前台运行
make run
# 方式 3：attach 到运行中的进程
dlv attach $(pgrep -f "hotplex.*gateway")
故障排查
| 问题 | 解决方案 |
|---|---|
go.mod requires go >= 1.26 | 升级 Go 到 1.26+ |
⚠ golangci-lint (missing) | brew install golangci-lint |
webchat-embed needs pnpm | npm install -g pnpm && cd webchat && pnpm install |
bind: address already in use | lsof -i :8888 检查并停止占用进程 |
⚠ goimports (missing) | go install golang.org/x/tools/cmd/goimports@latest |