本地运行与 prod 生产运行部署指南

这套 Spring Cloud Alibaba 项目有两种主要运行方式：本地开发默认使用 dev Profile，直接连接共享开发环境；生产运行显式切换到 prod Profile，Nacos、MySQL、Zipkin 都通过本机 127.0.0.1 访问。本文按“先跑起来，再部署到生产”的顺序整理完整步骤。

真正需要部署的服务只有 4 个：

service-common 是公共库，已经打进各业务服务的 Fat JAR；MP-Generator 是代码生成工具，都不需要作为服务部署。

本地源码运行

本地开发机准备：

1. JDK 21+
2. Maven 3.9+
3. IDEA 或其它 IDE
4. 可访问共享 Nacos、MySQL、Zipkin、MailHog

确认版本：

java -version
mvn -version

在项目根目录构建：

mvn clean package -DskipTests

生成的可执行 JAR：

service-provider/target/service-provider-1.0.0.jar
service-consumer/target/service-consumer-1.0.0.jar
service-gateway/target/service-gateway-1.0.0.jar
service-mail/target/service-mail-1.0.0.jar

https://github.com/springvortex/spring-cloud-alibaba/blob/release/v1.0.0/README.md

数据库密码和 SMTP 密码使用 Jasypt 密文，启动时必须注入密钥。IDEA 建议在 Run Configuration 的 VM Options 写：

-Djasypt.encryptor.password=your-secret-key

命令行方式：

java -Djasypt.encryptor.password=your-secret-key \
  -jar service-provider-1.0.0.jar

推荐启动顺序：

1. service-provider
2. service-mail
3. service-consumer
4. service-gateway

第一次验证最小链路时，只启动 Provider 和 Gateway 就够了。默认不需要传 --spring.profiles.active，包内默认激活 dev。

本地验证：

curl http://127.0.0.1/api/v1/provider/port
curl http://127.0.0.1/api/v1/provider/user/1
curl http://127.0.0.1/api/v1/consumer/feign/port

开发环境聚合 Swagger：

http://127.0.0.1/swagger-ui.html

完全本地隔离运行

默认 dev 连接共享环境。如果想在本地搭一套完全隔离环境，需要安装 MySQL 8、Nacos 3、Zipkin、MailHog 和 JDK 21。

临时切换可以用命令行覆盖，以 Provider 为例：

JDBC_URL="jdbc:mysql://127.0.0.1:3306/spring_cloud_alibaba"
JDBC_PARAMS="?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&sslMode=REQUIRED"

java -Djasypt.encryptor.password=your-secret-key \
  -jar service-provider-1.0.0.jar \
  --spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 \
  --spring.datasource.url="$JDBC_URL$JDBC_PARAMS" \
  --spring.datasource.username=spring_cloud_alibaba \
  --spring.datasource.password=your-db-password \
  --management.tracing.export.zipkin.endpoint=http://127.0.0.1:9411/api/v2/spans

Gateway 和 Consumer 需要覆盖 Nacos 与 Zipkin 地址；Mail 还需要覆盖 SMTP 配置。也可以直接修改各服务的 application-dev.yaml 为本机地址后重新打包，但要注意不要把本地地址和敏感密码误提交。

prod 运行前提

生产服务器需要：

1. JDK 21+
2. MySQL 8 已运行，库表已初始化
3. Nacos 3 已运行
4. Zipkin 已运行
5. 生产 SMTP 账号已配置
6. Jasypt 密钥已准备

prod Profile 访问的基础设施：

https://github.com/springvortex/spring-cloud-alibaba/blob/release/v1.0.0/service-provider/src/main/resources/application-prod.yaml

生产网络边界：

Linux 普通用户不能绑定 80 端口，Gateway 建议改用 9000：

--server.port=9000

也可以由 Nginx 或云负载均衡监听 80/443，再转发到 Gateway 的 9000。

获取部署包

本地打包：

mvn clean package -DskipTests

只需要拷贝 4 个可执行 JAR：

service-gateway-1.0.0.jar
service-provider-1.0.0.jar
service-consumer-1.0.0.jar
service-mail-1.0.0.jar

建议服务器目录：

/opt/spring-cloud-alibaba/
├── gateway/
├── provider/
├── consumer/
└── mail/

仓库的 Java CI 也会在构建后收集可执行 JAR，并上传为 application-jars Artifact。

https://github.com/springvortex/spring-cloud-alibaba/blob/release/v1.0.0/.github/workflows/maven.yml

当前工作流监听 main 分支；部署其它分支时，建议在本地构建或另外配置工作流。

Linux prod 启动

第一次部署可以先前台启动 Provider 观察日志：

cd /opt/spring-cloud-alibaba/provider

java -Xms256m -Xmx512m \
  -Djasypt.encryptor.password=your-secret-key \
  -jar service-provider-1.0.0.jar \
  --spring.profiles.active=prod

确认成功后再后台启动：

nohup java -Xms256m -Xmx512m \
  -Djasypt.encryptor.password=your-secret-key \
  -jar service-provider-1.0.0.jar \
  --spring.profiles.active=prod \
  > provider.out 2> provider.err &

echo $! > provider.pid

Gateway：

nohup java -Xms256m -Xmx512m \
  -Djasypt.encryptor.password=your-secret-key \
  -jar service-gateway-1.0.0.jar \
  --spring.profiles.active=prod \
  --server.port=9000 \
  > gateway.out 2> gateway.err &

echo $! > gateway.pid

Consumer 与 Mail 同理，替换 JAR 名、输出文件和 PID 文件名即可。

更推荐 systemd 管理。先创建权限收紧的密钥文件：

sudo mkdir -p /etc/spring-cloud-alibaba
sudo vim /etc/spring-cloud-alibaba/provider.env

写入：

JASYPT_ENCRYPTOR_PASSWORD=your-secret-key

设置权限：

sudo chown root:root /etc/spring-cloud-alibaba/provider.env
sudo chmod 600 /etc/spring-cloud-alibaba/provider.env

创建 spring-provider.service：

[Unit]
Description=Spring Cloud Alibaba Provider
After=network.target mysql.service nacos.service

[Service]
User=spring
Group=spring
WorkingDirectory=/opt/spring-cloud-alibaba/provider
EnvironmentFile=/etc/spring-cloud-alibaba/provider.env
ExecStart=/usr/bin/java -Xms256m -Xmx512m -jar service-provider-1.0.0.jar --spring.profiles.active=prod
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启动并设置开机自启：

sudo systemctl daemon-reload
sudo systemctl enable --now spring-provider
sudo journalctl -u spring-provider -f

其它服务复制 unit 后替换目录、JAR 和描述即可。

Windows prod 启动

设置密钥：

$env:JASYPT_ENCRYPTOR_PASSWORD = "your-secret-key"

后台启动 Provider：

Start-Process -FilePath "java" `
  -ArgumentList `
    "-Xms256m", "-Xmx512m", `
    "-Djasypt.encryptor.password=your-secret-key", `
    "-jar", "service-provider-1.0.0.jar", `
    "--spring.profiles.active=prod" `
  -RedirectStandardOutput "provider.out" `
  -RedirectStandardError "provider.err"

Windows 同样只暴露 Gateway，其它端口用防火墙封住。

生产验证

假设 Gateway 使用 9000：

curl http://127.0.0.1:9000/api/v1/provider/port
curl http://127.0.0.1:9000/api/v1/consumer/feign/port

验证邮件：

curl -X POST "http://127.0.0.1:9000/api/v1/mail/send" \
  -H "Content-Type: application/json" \
  -d '{"toEmails":"test@example.com","subject":"Prod Test","content":"Hello","isHtml":false}'

邮件返回看 data.status：1 成功，2 失败并查看 errorMsg。

再确认 Nacos 服务列表：

service-provider
service-consumer
service-mail
service-gateway

最后到 Zipkin 查询 Gateway 日志里的 traceId，确认整条调用链完整。

常见问题

Jasypt 解密失败

确认密钥已通过 VM 参数或环境变量注入。IDEA 修改系统环境变量后要彻底退出再重新打开；VM Options 里写 -Djasypt.encryptor.password=... 最可靠。

服务注册不上 Nacos

在服务器上确认 Nacos 可访问，并检查 8848、9848、9849、7848 内网通信端口。只开放 8848 不一定满足客户端通信。

Gateway 返回 503

优先检查下游服务是否启动、是否注册到 Nacos、路由服务名是否正确，以及是否触发 Sentinel 路由熔断。

Gateway 返回 404

确认访问的是完整前缀：

/api/v1/provider/**
/api/v1/consumer/**
/api/v1/mail/**

数据库连接失败

先用命令行验证：

mysql -h 127.0.0.1 -P 3306 -u spring_cloud_alibaba -p

再检查账号 Host、密码密文、Jasypt 密钥、SSL 配置和库表初始化状态。

上线检查清单

1. Java 版本为 21+。
2. 4 个服务都显式使用 prod Profile。
3. Jasypt 密钥没有写入 Git 和日志。
4. MySQL、Nacos、Zipkin 均不暴露公网。
5. 公网只暴露 Gateway。
6. Linux 上 Gateway 不用普通用户绑定 80。
7. Nacos 实例完整。
8. Gateway 冒烟请求成功。
9. Zipkin 链路完整。
10. 日志有采集和轮转方案。

这套项目的部署核心是：本地用 dev 降低准备成本，生产用 prod 收敛配置和网络边界；业务服务留在内网，所有外部流量统一从 Gateway 进入。