topfans/backend

Top Fans Backend

微服务后端项目，使用 Go 1.25.5 和 gRPC。

项目架构

• UserSocialService: 用户与社交服务（用户、社交、展位、任务）
• AssetChainService: 资产与链服务
• Gateway: API 网关（REST API）

环境要求

• Go 1.25.5
• Protocol Buffers Compiler (protoc) 3.x+
• Make

快速开始

1. 安装 Go 环境

# 使用 Homebrew (macOS)
brew install go@1.25.5

# 或从官网下载
# https://go.dev/dl/

2. 配置环境

运行安装脚本：

chmod +x scripts/setup.sh
./scripts/setup.sh

或手动安装：

# 设置 Go 代理（可选，加速下载）
export GOPROXY=https://goproxy.cn,direct

# 下载依赖
go mod download
go mod tidy

# 安装 protoc 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

# 安装 googleapis
go get github.com/googleapis/googleapis

3. 安装 Protocol Buffers

# macOS
brew install protobuf

# Linux (Ubuntu/Debian)
apt-get install protobuf-compiler

# Linux (CentOS/RHEL)
yum install protobuf-compiler

4. 环境变量配置 ⚠️

本项目有两套互相独立的配置文件,设计上是"二选一"关系,不要混用:

文件	用途	何时生效
backend/.env	Dev(本机开发) 配置	./backend/dev.sh 自动 source
backend/deploy/envs/*.env	生产多机部署 配置(每个服务一份)	仅在目标服务器上由 systemd / docker / 部署脚本 source

为什么不能混用 — 同一个变量在两套里值不同,后者会覆盖前者:

变量	backend/.env(dev)	deploy/envs/gateway.env(生产)	混用后果
JWT_SECRET	topfans-secret-key-please-change-in-production	your_secure_jwt_secret_here	所有 token 校验失败,需要登录的接口 401
DUBBO_GALLERY_SERVICE_URL	tri://127.0.0.1:20004	tri://localhost:20001	调用 gallery 服务的接口连接失败
DUBBO_ACTIVITY_SERVICE_URL	tri://127.0.0.1:20005	tri://localhost:20004	调用 activity 服务的接口连接失败
OSS_ACCESS_KEY_ID	LTAI5t99tafzfyrzbbEbjryH	LTAI5t6QcdJHpYbCPxM8SXYE	OSS 上传/下载 403
DB_USER / DB_PASSWORD	postgres / 123456	haihuizhu / admin	启动期就连不上 DB
ENV	development	production	日志格式、限流策略等会按生产行为跑

dev.sh 当前的加载规则(见 dev.sh:load_service_env):

• dev.sh 启动时只 source backend/.env
• 启动每个服务前,按服务名(去掉 Service 后缀)source 对应的 deploy/envs/<name>.env,但仅对 userService 生效
• userService 之所以特殊:它的 deploy/envs/user.env 里有 SMS_ACCESS_KEY_ID / SMS_ACCESS_KEY_SECRET 等 backend/.env 没有的变量,需要叠加
• 其他服务不再 source deploy/envs/ — 否则会被生产端口/密钥覆盖 dev 端口/密钥,导致接口大面积失败(典型症状:token 401、Dubbo 调用超时、OSS 403)

生产部署时(由部署脚本负责,与 dev.sh 无关):

• 把对应服务的 deploy/envs/<name>.env 放到目标服务器的 /etc/topfans/<name>.env
• systemd unit / docker-compose 引用该文件
• 不要 source backend/.env

新增配置项时的纪律:

1. 如果是 dev 和生产都需要的(如 DB_*、Dubbo URL 模板),在 backend/.env 改 + 在 deploy/envs/*.env 同步改
2. 如果仅生产需要(如 SMS_*、OSS 角色),只改 deploy/envs/<name>.env
3. 如果仅 dev 需要(如本地 mock 开关),只改 backend/.env
4. 改完后,在 dev 环境跑一次 ./dev.sh 验证没有端口/密钥错乱

---

5. 生成代码

# 生成 gRPC 代码
make proto

# 生成 REST API 代码和 Swagger 文档
make swagger

# 生成所有代码
make all

6. 启动服务

# 一键启动所有服务(带文件热更新)
./dev.sh

# 或者只跑某个服务(略)
# 详见 dev.sh 注释

启动后会监听:

• Gateway: http://localhost:8080
• UserService: tri://localhost:20000
• Swagger UI: http://localhost:8080/swagger/index.html

⚠️ 启动前确认 backend/.env 里的 DB_HOST/REDIS_HOST 在本机能通(默认 localhost)。如果用远程 DB/Redis,改 backend/.env 而不是 deploy/envs/*.env。

项目结构

backend/
├── api/
│   └── gateway/          # 生成的 REST API Gateway 代码
├── pkg/
│   └── proto/            # 生成的 gRPC 代码
├── proto/                # Proto 定义文件
│   ├── common.proto
│   ├── user.proto
│   └── asset-chain.proto
├── swagger/              # Swagger 文档
├── scripts/              # 脚本文件
├── go.mod                # Go 模块定义
├── go.work               # Go 工作区配置
├── Makefile              # 构建脚本
└── README.md

开发工具

代码检查

项目使用 golangci-lint 进行代码检查：

# 安装 golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# 运行检查
golangci-lint run

代码格式化

# 格式化代码
go fmt ./...

# 整理 imports
goimports -w .

依赖管理

主要依赖：

• google.golang.org/protobuf: Protocol Buffers Go 支持
• google.golang.org/grpc: gRPC 框架
• github.com/grpc-ecosystem/grpc-gateway/v2: gRPC 到 REST 的转换
• github.com/gin-gonic/gin: HTTP Web 框架
• github.com/googleapis/googleapis: Google API 定义

Makefile 命令

make help          # 显示帮助信息
make proto         # 生成 gRPC 代码
make swagger       # 生成 REST API 代码和 Swagger 文档
make all           # 生成所有代码
make clean-proto   # 清理生成的 proto 代码
make clean-swagger # 清理生成的 gateway 代码和 swagger
make clean         # 清理所有生成的代码

版本管理

• Go 版本: 1.25.5 (在 .go-version 文件中指定)
• 使用 Go Workspace 模式管理多模块项目

注意事项

1. 生成的代码（pkg/proto、api/gateway）不要手动修改
2. 修改接口时，先更新 .proto 文件，再运行 make all 重新生成
3. 确保 GOPATH/bin 在 PATH 中，以便使用 protoc 插件

问题排查

protoc 插件未找到

确保 $GOPATH/bin 或 $HOME/go/bin 在 PATH 中：

export PATH=$PATH:$(go env GOPATH)/bin

googleapis 未找到

go get github.com/googleapis/googleapis

生成代码失败

检查 protoc 版本：

protoc --version  # 应该是 3.x 版本

许可证

[添加许可证信息]