topfans/backend/docs/服务器部署指南.md

TopFans 后端服务器部署指南

本指南适用于在全新的 Linux 服务器上从零开始部署 TopFans 后端项目。

目录

• 系统要求
• 第一步：服务器基础环境配置
• 第二步：安装 Go 环境
• 第三步：安装 PostgreSQL 数据库
• 第四步：安装 Protobuf 编译器
• 第五步：部署后端代码
• 第六步：配置环境变量
• 第七步：编译并安装二进制文件
• 第八步：配置进程守护（systemd）
• 第九步：启动与验证
• 更新部署
• 故障排查
• 性能优化建议
• 多机部署说明

---

系统要求

硬件要求

• CPU: 2 核及以上
• 内存: 4 GB 及以上（推荐 8 GB）
• 磁盘: 20 GB 及以上可用空间
• 网络: 稳定的互联网连接

操作系统

• Ubuntu 20.04 LTS / 22.04 LTS（推荐）
• CentOS 7 / 8
• Debian 10 / 11

服务端口

服务	端口	协议
Gateway（HTTP REST API）	8080	HTTP
User Service	20000	Dubbo/Triple
Gallery Service	20001	Dubbo/Triple
Social Service	20002	Dubbo/Triple
Asset Service	20003	Dubbo/Triple
Activity Service	20004	Dubbo/Triple
PostgreSQL	5432	TCP（仅内网访问）

---

第一步：服务器基础环境配置

ssh root@101.132.250.62

R251Y>Y8inL_BM=W

1.1 更新系统包

# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# CentOS/RHEL
sudo yum update -y

1.2 安装基础工具

# Ubuntu/Debian
sudo apt install -y git curl wget vim build-essential unzip

# CentOS/RHEL
sudo yum install -y git curl wget vim gcc gcc-c++ make unzip

1.3 配置防火墙

# Ubuntu/Debian（ufw）
sudo ufw allow 8080/tcp
sudo ufw allow 20000:20004/tcp
sudo ufw enable

# CentOS/RHEL（firewalld）
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=20000-20004/tcp
sudo firewall-cmd --reload

安全提示: 5432 端口（PostgreSQL）不应对公网开放，仅允许服务器本机访问。

---

第二步：安装 Go 环境

2.1 下载并安装 Go

cd /tmp
wget https://go.dev/dl/go1.25.6.linux-amd64.tar.gz

sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.6.linux-amd64.tar.gz
rm go1.25.6.linux-amd64.tar.gz

2.2 配置环境变量

vim ~/.bashrc

# 在文件末尾添加：
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
export GOPROXY=https://goproxy.cn,direct
export GO111MODULE=on

source ~/.bashrc

2.3 验证安装

go version
# 预期输出: go version go1.25.6 linux/amd64

---

第三步：安装 PostgreSQL 数据库

3.1 安装 PostgreSQL

# Ubuntu/Debian
sudo apt install -y postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# CentOS/RHEL
sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum install -y postgresql14-server postgresql14-contrib
sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
sudo systemctl start postgresql-14
sudo systemctl enable postgresql-14

3.2 创建数据库和用户

sudo -u postgres psql

-- 创建数据库
CREATE DATABASE "top-fans";

-- 创建用户（与 common.env 中 DB_USER / DB_PASSWORD 保持一致）
CREATE USER topfans_user WITH PASSWORD 'your_secure_password_here';

-- 授予权限
GRANT ALL PRIVILEGES ON DATABASE "top-fans" TO topfans_user;

\q

3.3 验证连接

psql -h localhost -U topfans_user -d top-fans

psql -h localhost -U haihuizhu -d top-fans
密码：Z^Bz8kbH.h~mMZ~!
# 输入密码后能成功连接即代表配置正确

---

第四步：安装 Protobuf 编译器

4.1 安装 protoc

# Ubuntu/Debian
sudo apt install -y protobuf-compiler

# 或手动安装最新版（CentOS 或需要特定版本时）
cd /tmp
wget https://github.com/protocolbuffers/protobuf/releases/download/v27.2/protoc-27.2-linux-x86_64.zip
sudo unzip protoc-27.2-linux-x86_64.zip -d /usr/local
rm protoc-27.2-linux-x86_64.zip

protoc --version

4.2 安装 Go protoc 插件

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install github.com/dubbogo/protoc-gen-go-triple/v3@latest

which protoc-gen-go
which protoc-gen-go-triple

---

第五步：部署后端代码

5.1 创建部署目录

# 二进制文件统一存放于 /opt/topfans
sudo mkdir -p /opt/topfans
sudo chown root:root /opt/topfans

# 配置文件存放于 /etc/topfans
sudo mkdir -p /etc/topfans
sudo chown root:root /etc/topfans
sudo chmod 750 /etc/topfans

5.2 克隆代码仓库

mkdir -p ~/projects
cd ~/projects

git clone https://github.com/your-org/TopFans.git
cd TopFans/backend

5.3 下载 Go 依赖

项目使用 Go Workspace（go.work），各模块独立管理依赖，需在每个模块目录下分别执行：

BASE=~/projects/TopFans/backend

# 主模块（共享 pkg）
cd $BASE && go mod download

# Gateway
cd $BASE/gateway && go mod download

# 各 Service
for svc in userService socialService galleryService assetService activityService; do
  cd $BASE/services/$svc && go mod download
done

---

第六步：配置环境变量（模板配置在deploy文件夹中

项目采用分层环境变量策略：公共配置一份，各服务私有配置一份，部署时分别写入 /etc/topfans/。

6.1 公共配置（所有服务共享）

sudo vim /etc/topfans/common.env

# ==================== 公共配置 ====================
ENV=production
LOG_LEVEL=info

# PostgreSQL 连接（多机部署时改为数据库服务器 IP）
DB_HOST=localhost
DB_PORT=5432
DB_USER=haihuizhu
DB_PASSWORD=Z^Bz8kbH.h~mMZ~!
DB_NAME=top-fans

6.2 各服务私有配置

User Service

sudo vim /etc/topfans/user.env

PORT=20000

Gallery Service

sudo vim /etc/topfans/gallery.env

PORT=20001
USER_SERVICE_URL=tri://localhost:20000
ASSET_SERVICE_URL=tri://localhost:20003

Social Service

sudo vim /etc/topfans/social.env

PORT=20002
USER_SERVICE_URL=tri://localhost:20000
ASSET_SERVICE_URL=tri://localhost:20003

Asset Service

sudo vim /etc/topfans/asset.env

PORT=20003
USER_SERVICE_URL=tri://localhost:20000

# 阿里云 OSS（替换为真实值）
OSS_REGION=cn-shanghai
OSS_BUCKET_NAME=top-fans-test
OSS_ACCESS_KEY_ID=LTAI5tNaAjTNiHnefMCG3q4J
OSS_ACCESS_KEY_SECRET=48wwZvNkUn1PO1xWjV4HuE5JjB6G7c
OSS_ROLE_ARN=acs:ram::1387642798143585:role/top-fans-oss-user

Activity Service

sudo vim /etc/topfans/activity.env

# ==================== Activity Service 私有配置 ====================
# 多机部署时将此文件放到 activity 服务器的 /etc/topfans/activity.env

# 服务端口
PORT=20004

# 下游服务地址（多机部署时改为对应服务器内网IP）
USER_SERVICE_URL=tri://localhost:20000
GALLERY_SERVICE_URL=tri://localhost:20001

Gateway

sudo vim /etc/topfans/gateway.env

GIN_MODE=release
SERVER_PORT=8080

# JWT 密钥（生产环境务必替换为随机强密码）
JWT_SECRET=your_secure_jwt_secret_here

# 下游服务地址（多机部署时改为对应服务器内网 IP）
DUBBO_USER_SERVICE_URL=tri://localhost:20000
DUBBO_GALLERY_SERVICE_URL=tri://localhost:20001
DUBBO_SOCIAL_SERVICE_URL=tri://localhost:20002
DUBBO_ASSET_SERVICE_URL=tri://localhost:20003
DUBBO_ACTIVITY_SERVICE_URL=tri://localhost:20004

6.3 保护配置文件权限

# 仅允许 topfans 用户读取
sudo chmod 640 /etc/topfans/*.env
sudo chown root:root /etc/topfans/*.env

---

第七步：编译并安装二进制文件

7.1 编译 Proto 文件（如有 .proto 变更）

cd ~/projects/TopFans/backend
bash scripts/compile-proto.sh

# 验证生成结果
ls pkg/proto/*/

7.2 编译所有服务

BASE=~/projects/TopFans/backend

# Gateway
cd $BASE/gateway
go build -ldflags="-s -w" -o /opt/topfans/gateway .

# User Service
cd $BASE/services/userService
go build -ldflags="-s -w" -o /opt/topfans/user-service .

# Gallery Service
cd $BASE/services/galleryService
go build -ldflags="-s -w" -o /opt/topfans/gallery-service .

# Social Service
cd $BASE/services/socialService
go build -ldflags="-s -w" -o /opt/topfans/social-service .

# Asset Service
cd $BASE/services/assetService
go build -ldflags="-s -w" -o /opt/topfans/asset-service .

# Activity Service
cd $BASE/services/activityService
go build -ldflags="-s -w" -o /opt/topfans/activity-service .

7.3 验证二进制文件

ls -lh /opt/topfans/
# 预期看到 6 个可执行文件：
# gateway  user-service  gallery-service  social-service  asset-service  activity-service

---

第八步：配置进程守护（systemd）

deploy/systemd/ 目录下已提供所有服务的 systemd 模板，直接复制后启用即可。

8.1 安装 systemd 服务文件

BASE=~/projects/TopFans/backend

sudo cp $BASE/deploy/systemd/topfans-user.service     /etc/systemd/system/
sudo cp $BASE/deploy/systemd/topfans-gallery.service  /etc/systemd/system/
sudo cp $BASE/deploy/systemd/topfans-social.service   /etc/systemd/system/
sudo cp $BASE/deploy/systemd/topfans-asset.service    /etc/systemd/system/
sudo cp $BASE/deploy/systemd/topfans-activity.service /etc/systemd/system/
sudo cp $BASE/deploy/systemd/topfans-gateway.service  /etc/systemd/system/

每个服务文件的核心内容如下（以 User Service 为例）：

[Unit]
Description=TopFans User Service
After=network.target postgresql.service

[Service]
User=topfans
WorkingDirectory=/opt/topfans
EnvironmentFile=/etc/topfans/common.env
EnvironmentFile=/etc/topfans/user.env
ExecStart=/opt/topfans/user-service
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

说明: ExecStart 只指定二进制路径，不传任何 flag。服务启动时自动读取 EnvironmentFile 中的环境变量作为 flag 默认值（优先级：CLI flag > ENV > 硬编码默认值）。

8.2 重载并启用所有服务

sudo systemctl daemon-reload

# 设置开机自启
sudo systemctl enable topfans-user topfans-gallery topfans-social \
                       topfans-asset topfans-activity topfans-gateway

---

第九步：启动与验证

9.1 按依赖顺序启动服务

# 1. 先启动无依赖的基础服务
sudo systemctl start topfans-user
sudo systemctl start topfans-asset

# 2. 启动依赖基础服务的上层服务
sudo systemctl start topfans-gallery
sudo systemctl start topfans-social
sudo systemctl start topfans-activity

# 3. 最后启动 Gateway
sudo systemctl start topfans-gateway

9.2 验证服务状态

# 查看所有服务状态
sudo systemctl status topfans-user topfans-gallery topfans-social \
                       topfans-asset topfans-activity topfans-gateway

# 检查端口监听
ss -tlnp | grep -E '8080|2000[0-4]'

9.3 测试 API

# 健康检查（Gateway）
curl -i http://localhost:8080/health

# 测试登录接口
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test"}'

9.4 查看日志

# 实时跟踪单个服务日志
sudo journalctl -u topfans-gateway -f

# 查看最近 100 行
sudo journalctl -u topfans-user -n 100

# 同时查看多个服务日志
sudo journalctl -u topfans-user -u topfans-social -f

---

更新部署

BASE=~/projects/TopFans/backend

# 1. 拉取最新代码
cd $BASE && git pull origin main

# 2. 重新编译（如有 .proto 变更先执行）
# bash scripts/compile-proto.sh

# 3. 重新编译所有二进制文件
cd $BASE/gateway         && go build -ldflags="-s -w" -o /opt/topfans/gateway .
cd $BASE/services/userService     && go build -ldflags="-s -w" -o /opt/topfans/user-service .
cd $BASE/services/galleryService  && go build -ldflags="-s -w" -o /opt/topfans/gallery-service .
cd $BASE/services/socialService   && go build -ldflags="-s -w" -o /opt/topfans/social-service .
cd $BASE/services/assetService    && go build -ldflags="-s -w" -o /opt/topfans/asset-service .
cd $BASE/services/activityService && go build -ldflags="-s -w" -o /opt/topfans/activity-service .

# 4. 重启所有服务
sudo systemctl restart topfans-user topfans-gallery topfans-social \
                        topfans-asset topfans-activity topfans-gateway

# 5. 确认服务全部正常
sudo systemctl status topfans-*

---

故障排查

问题 1: 服务无法启动

# 查看详细错误日志
sudo journalctl -u topfans-gateway -xe

# 检查端口是否被占用
sudo ss -tlnp | grep 8080

# 手动执行二进制，直接查看输出
sudo -u topfans \
  env $(cat /etc/topfans/common.env /etc/topfans/gateway.env | grep -v '^#') \
  /opt/topfans/gateway

问题 2: 数据库连接失败

# 确认 PostgreSQL 运行中
sudo systemctl status postgresql

# 验证连接参数（与 common.env 一致）
psql -h localhost -U topfans_user -d top-fans

# 检查 common.env 中的数据库配置
sudo cat /etc/topfans/common.env | grep DB_

问题 3: Dubbo 服务连接失败

# 检查下游服务是否运行并监听端口
sudo ss -tlnp | grep -E '2000[0-4]'

# 检查服务日志
sudo journalctl -u topfans-user -n 50

# 确认服务私有 env 中的 URL 配置正确
sudo cat /etc/topfans/social.env

问题 4: 环境变量未生效

# 查看 systemd 实际注入的环境变量
sudo systemctl show topfans-user --property=Environment

# 手动验证 env 文件语法（不应含 export 前缀）
sudo cat /etc/topfans/common.env

问题 5: Proto 文件编译失败

# 检查工具是否安装
protoc --version
which protoc-gen-go
which protoc-gen-go-triple

# 手动编译单个 proto 文件测试
cd ~/projects/TopFans/backend
protoc --proto_path=proto \
  --go_out=pkg/proto/user \
  --go_opt=paths=source_relative \
  user.proto

---

性能优化建议

1. 数据库优化

sudo vim /etc/postgresql/14/main/postgresql.conf

# 根据服务器内存调整（以下为 8 GB 内存示例）
shared_buffers = 2GB
effective_cache_size = 6GB
maintenance_work_mem = 512MB
work_mem = 32MB
max_connections = 200

sudo systemctl restart postgresql

2. 系统参数优化

sudo vim /etc/security/limits.conf
# 添加：
* soft nofile 65535
* hard nofile 65535

sudo vim /etc/sysctl.conf
# 添加：
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
net.ipv4.ip_local_port_range = 10000 65000

sudo sysctl -p

3. 日志轮转

sudo vim /etc/logrotate.d/topfans

/var/log/topfans/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0644 topfans topfans
}

---

监控与备份

服务健康检查脚本

vim ~/health-check.sh

#!/bin/bash
SERVICES=(topfans-user topfans-gallery topfans-social topfans-asset topfans-activity topfans-gateway)
LOG=/var/log/topfans-health.log

for svc in "${SERVICES[@]}"; do
    if ! systemctl is-active --quiet "$svc"; then
        echo "$(date '+%F %T'): $svc is down, restarting..." >> "$LOG"
        systemctl restart "$svc"
    fi
done

chmod +x ~/health-check.sh
# 每 5 分钟检查一次
(crontab -l 2>/dev/null; echo "*/5 * * * * /home/topfans/health-check.sh") | crontab -

数据库备份脚本

vim ~/backup-db.sh

#!/bin/bash
BACKUP_DIR="/home/topfans/backups"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"
pg_dump -h localhost -U topfans_user -d top-fans > "$BACKUP_DIR/topfans_$DATE.sql"
gzip "$BACKUP_DIR/topfans_$DATE.sql"

# 保留最近 7 天
find "$BACKUP_DIR" -name "*.sql.gz" -mtime +7 -delete
echo "$(date '+%F %T'): Backup done: topfans_$DATE.sql.gz" >> /var/log/topfans-backup.log

chmod +x ~/backup-db.sh
# 每天凌晨 2 点备份
(crontab -l 2>/dev/null; echo "0 2 * * * /home/topfans/backup-db.sh") | crontab -

---

多机部署说明

当业务量增长需要将服务拆分到多台服务器时，只需修改各服务器上对应服务私有 env 文件中的下游地址，将 localhost 替换为目标服务器的内网 IP，无需改动代码。

示例：双机部署（DB 服务器 + 应用服务器）

DB 服务器（IP: 10.0.0.10）：仅运行 PostgreSQL。

应用服务器（IP: 10.0.0.20）：运行所有后端服务，修改 common.env 中的 DB 地址：

# /etc/topfans/common.env（应用服务器）
DB_HOST=10.0.0.10    # 改为 DB 服务器内网 IP

示例：三机部署（拆分 Asset/Gallery 服务）

服务器	运行服务
10.0.0.20（应用1）	userService, socialService, activityService, gateway
10.0.0.21（应用2）	galleryService, assetService
10.0.0.10（DB）	PostgreSQL

在应用1服务器的 social.env 和 activity.env 中：

# /etc/topfans/social.env（应用1服务器）
ASSET_SERVICE_URL=tri://10.0.0.21:20003   # 指向应用2内网 IP

在应用1的 gateway.env 中：

# /etc/topfans/gateway.env（应用1服务器）
DUBBO_GALLERY_SERVICE_URL=tri://10.0.0.21:20001
DUBBO_ASSET_SERVICE_URL=tri://10.0.0.21:20003

后续扩展: 如需引入服务注册与发现（如 Nacos），各服务的 configs/dubbo.yaml 已预留占位配置，启用时取消注释并在 main.go 中调用 config.Load() 即可。

---

安全建议

1. 强密码: DB_PASSWORD、JWT_SECRET 使用 32 位以上随机字符串
2. 最小权限: 服务以 topfans 用户运行，不使用 root
3. env 文件权限: chmod 640，仅 topfans 用户可读
4. 防火墙: 仅对外开放 8080，Dubbo 端口（20000-20004）限内网访问
5. HTTPS: 生产环境通过 Nginx 反向代理对外暴露 443 端口
6. 定期更新: 及时更新系统包和 Go 依赖
7. 备份验证: 每月手动恢复一次备份，验证其可用性