← 返回学习路线

SYSTEM

单体部署上线笔记

后端实战
src/content/notes/blog-dev/单体部署上线.md

单体部署上线笔记

项目:个人博客(Spring Boot 单体 + Vue3 前端) 服务器:阿里云 ECS(中国香港),Alibaba Cloud Linux,2C4G 公网 IP:[公网IP已隐藏] 部署方式:中间件走 Docker Compose,应用 jar 走 systemd,前端由 Nginx 托管 + 反代


一、总体架构

浏览器 (Vue3 SPA)
   │
   ▼
Nginx :80  ── 托管 /opt/blog/dist 静态资源
   │         ├─ /api  → 反代 http://127.0.0.1:8088
   │         └─ /ws   → 反代 http://127.0.0.1:8088 (WebSocket/SockJS)
   ▼
Spring Boot jar :8088 (systemd 常驻)
   ├─ MySQL 8     (docker, 127.0.0.1:3306)   # 只绑内网
   ├─ Redis 7     (docker, 127.0.0.1:6379)
   ├─ RabbitMQ    (docker, 127.0.0.1:5672)
   └─ DeepSeek API (外部, AI 摘要)

关键设计:三个中间件全部绑定 127.0.0.1,安全组只需放行 22 和 80,3306/6379/5672 不对外暴露,比直接安装更安全。


二、服务器侧:环境准备(已完成 ✅)

1. 基础环境安装

# JDK17 + Nginx(epel-release 提供 nginx,需先装)
yum install -y java-17-openjdk epel-release nginx
java -version   # 确认 17
nginx -v

# 创建日志目录(systemd 的 StandardOutput/StandardError 依赖它存在)
mkdir -p /opt/blog/logs

⚠️ 坑:Alibaba Cloud Linux 是 yum/dnf 系,不是 Ubuntu 的 apt;直接装 MySQL8/Erlang+RabbitMQ 很折腾,所以中间件改用 Docker 绕开。

2. 中间件 docker-compose(/opt/blog/docker-compose.yml)

services:
  mysql:
    image: mysql:8.0
    container_name: blog-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: <root密码>
      MYSQL_DATABASE: blog_db
      MYSQL_USER: blog
      MYSQL_PASSWORD: <业务密码>
      TZ: Asia/Shanghai
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    ports:
      - "127.0.0.1:3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql

  redis:
    image: redis:7
    container_name: blog-redis
    restart: always
    command: redis-server --requirepass <redis密码> --appendonly yes
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - redis-data:/data

  rabbitmq:
    image: rabbitmq:3.13-management
    container_name: blog-rabbitmq
    restart: always
    environment:
      RABBITMQ_DEFAULT_USER: admin
      RABBITMQ_DEFAULT_PASS: admin123
    ports:
      - "127.0.0.1:5672:5672"
      - "127.0.0.1:15672:15672"
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq

volumes:
  mysql-data:
  redis-data:
  rabbitmq-data:

数据持久化:三个中间件数据都存在 docker volume,关机/重启不丢失。

3. systemd 服务模板(/etc/systemd/system/blog.service)

[Unit]
Description=Blog 单体 SpringBoot 服务
After=network.target docker.service
Wants=docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/blog
ExecStart=/usr/bin/java -Xms256m -Xmx512m -jar /opt/blog/blog-0.0.1-SNAPSHOT.jar
StandardOutput=file:/opt/blog/logs/blog.log
StandardError=file:/opt/blog/logs/blog-error.log
Restart=on-failure
RestartSec=5
SuccessExitStatus=143
EnvironmentFile=/etc/blog/blog.env

[Install]
WantedBy=multi-user.target

4. 密钥环境文件(/etc/blog/blog.env,权限 600)

mkdir -p /etc/blog
cat > /etc/blog/blog.env <<EOF
DB_HOST=127.0.0.1
DB_USERNAME=blog
DB_PASSWORD=<MySQL业务密码>
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=<Redis密码>
RABBITMQ_HOST=127.0.0.1
RABBITMQ_USERNAME=admin
RABBITMQ_PASSWORD:[已隐藏]
JWT_SECRET_KEY=$(openssl rand -base64 48)
DEEPSEEK_API_KEY=<你的Key>
CORS_ALLOWED_ORIGINS=http://[公网IP已隐藏]
EOF
chmod 600 /etc/blog/blog.env
chown root:root /etc/blog/blog.env

⚠️ heredoc 注意:env 文件用不带引号 <<EOF(让 $(openssl ...) 展开成真实随机串);nginx 配置用带引号 <<'EOF'(保留 $host/$uri 等 nginx 变量不被 bash 展开)。规律:想让 bash 展开变量 → 不带引号;想原样保留 $ → 带引号。

5. Nginx 反代配置(/etc/nginx/conf.d/blog.conf)

server {
    listen 80;
    server_name [公网IP已隐藏];

    # 前端静态资源(SPA history 路由)
    location / {
        root /opt/blog/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # 后端接口转发(原样透传 /api/**)
    location /api {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket / SockJS(评论实时推送)
    location /ws {
        proxy_pass http://127.0.0.1:8088;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

校验:nginx -t → syntax is ok / test is successful ✅


三、遇到的问题与解决方案(重点复习)

# 问题 原因 解决方案
1 systemd 服务显示 inactive (dead) jar 还没上传,属正常 等 jar 上传后 systemctl enable --now blog
2 终端执行 proxy_set_header ... 报 command not found Nginx 配置指令被当 shell 命令敲了 指令必须写进配置文件,用 heredoc 写入
3 误敲命令残留 proxy_set_header> 出现在粘贴回显里 终端回显插曲,未写入文件 用 cat + nginx -T 双重确认文件真实内容
4 Alibaba Cloud Linux 装 MySQL/RabbitMQ 太折腾 yum 系 + Erlang 兼容问题 中间件改用 Docker Compose 一键拉起
5 香港节点访问 GitHub 慢 网络限制 下载走阿里云镜像源 mirrors.aliyun.com
6 systemd 模板漏配密钥 只写了连接参数 补 JWT_SECRET_KEY(openssl 随机)、DEEPSEEK_API_KEY
7 CORS 行用了反引号 systemd 不认 shell 反引号 去掉反引号直接写 URL
8 明文密钥放 unit 文件有泄露风险 644 权限任何用户可读 集中到 /etc/blog/blog.env + chmod 600 + EnvironmentFile
9 Windows 私钥权限过大 SSH 拒绝 OpenSSH 校验严格 属性→安全→高级→关闭继承,只留本机账号读取权限
10 密钥绑定实例后无法登录 绑定必须重启实例 重启 ECS 实例使密钥生效
11 业务不通排查方向 — 优先查阿里云安全组是否放行对应端口
12 env 文件 heredoc 若用带引号 EOF $(openssl...) 不展开 用不带引号 <<EOF,写后 cat 验证是具体串

JWT 密钥为什么必须生产覆盖:application.yml 里有写死的 dev 默认密钥,上线不覆盖的话,任何看过代码的人都能伪造登录 Token。用 openssl rand -base64 48 生成不可猜测随机串。


四、当前状态

  • ✅ 服务器环境(JDK17/Nginx/日志目录)、docker-compose、systemd 模板、nginx 配置、密钥文件全部就绪
  • ✅ Redis 连通正常;nginx 语法校验通过;blog 服务 inactive(dead) 属正常,等 jar 包
  • ⏸ 准备使用节省停机模式关机节省 ECS 试用额度
    • 实例不会释放,磁盘全部保留
    • ⚠️ 唯一风险:公网 IP 可能变动

五、剩下要做(本地电脑)

  1. 修改 SpringBoot 配置:密码与服务器 docker-compose 保持一致,填入 DeepSeek 密钥
  2. Maven 打包后端 jar:.\mvnw.cmd clean package -DskipTests
  3. 前端构建:npm run build 生成 dist
  4. 上传 jar 到 /opt/blog/、dist 到 /opt/blog/dist/

六、下次开机后执行

cd /opt/blog
docker compose up -d
systemctl start blog
systemctl reload nginx

⚠️ 开机先看公网 IP,如果变了,同步更新 nginx 和 systemd 里的 IP。 补充:由于 systemd unit 里 ExecStart 用的是绝对路径 jar 名,上传 jar 时保持文件名一致;CORS_ALLOWED_ORIGINS 和 server_name 的 IP 也要跟着更新。


七、全链路验证命令(部署完成后)

BASE=http://[公网IP已隐藏]
# 1 公开接口
curl $BASE/api/site/config
# 2 注册
curl -X POST $BASE/api/user/register -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456","nickname":"演示用户"}'
# 3 登录拿 token
TOKEN=$(curl -s -X POST $BASE/api/user/login -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456"}' | jq -r '.data.token')
# 4 发文(内容放 body,别放 URL)
curl -X POST $BASE/api/article/create -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"上线测试","content":"这是上云验证正文……","categoryId":1}'
# 5 评论
curl -X POST "$BASE/api/comment/create?articleId=1&content=第一条评论" \
  -H "Authorization: Bearer $TOKEN"
# 6 点赞
curl -X POST "$BASE/api/like/article/1" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" -d '{"action":"like"}'
# 7 等 5-10 秒查详情看 AI 摘要
curl $BASE/api/article/1

浏览器访问 http://[公网IP已隐藏]:注册→登录→发文→评论→点赞→AI 摘要;开两个标签页验证评论实时推送(/ws 通了)。


八、面试可讲的亮点

  • 中间件容器化(docker-compose 编排 MySQL/Redis/RabbitMQ,数据卷持久化)
  • 应用层 systemd 常驻(自动重启、日志落盘)
  • Nginx 反向代理(静态托管 + /api 反代 + WebSocket Upgrade)
  • 密钥安全:EnvironmentFile 集中管理 + chmod 600 最小权限,JWT 密钥 openssl 随机生成生产覆盖

九、部署上线完成记录(2026-08-16 补充)

全链路验证通过,公网 http://[公网IP已隐藏] 一切功能正常,部署正式完成 ✅

一、MySQL 数据库侧

  1. 清空旧 MySQL 数据卷,全新初始化容器:删除旧 mysql-data 卷后重建容器,保证数据目录干净,容器首次启动自动初始化出 blog_db 库。

    cd /opt/blog
    docker compose down
    docker volume rm blog_mysql-data    # 清空旧数据卷,重新初始化
    docker compose up -d
  2. 创建远程通用账号 blog@%:密码 <业务密码>,授予 blog_db 全权限,供 Spring Boot 从宿主机网络访问容器内的 MySQL:

    docker exec blog-mysql mysql -uroot -p<root密码> -e "
    CREATE USER IF NOT EXISTS 'blog'@'%' IDENTIFIED BY '<业务密码>';
    GRANT ALL PRIVILEGES ON blog_db.* TO 'blog'@'%';
    FLUSH PRIVILEGES;"
  3. 开放 root 远程访问权限:解决应用连接时报 Access denied for user 'blog'@'172.19.0.1'。排查方法:确认 mysql.user 中 blog@% 用户存在、密码与 /etc/blog/blog.env 一致、权限授予正确。

    docker exec blog-mysql mysql -uroot -p<root密码> \
      -e "SELECT user, host, authentication_string FROM mysql.user WHERE user='blog';"

二、systemd 服务配置核心问题与修复

  1. 原方案:依赖 EnvironmentFile=/etc/blog/blog.env 读取全部环境变量。

  2. 故障现象:文件权限(600)、无 CRLF 换行、键值格式全部合规,但 systemd 完全加载不到变量——systemctl show blog 中 Environment= 为空,应用因缺 DB_PASSWORD 等变量启动失败。

  3. 最终修改:删除 EnvironmentFile 配置,改用多条 Environment="KEY=value" 硬编码写入全部 DB/Redis/MQ/JWT 变量,规避低版本 systemd 读取 env 文件的兼容性 bug。

    [Service]
    ...
    Environment="DB_HOST=127.0.0.1"
    Environment="DB_USERNAME=blog"
    Environment="DB_PASSWORD=<业务密码>"
    Environment="REDIS_HOST=127.0.0.1"
    Environment="REDIS_PASSWORD=<Redis密码>"
    Environment="RABBITMQ_HOST=127.0.0.1"
    Environment="RABBITMQ_USERNAME=admin"
    Environment="RABBITMQ_PASSWORD:[已隐藏]
    Environment="JWT_SECRET_KEY=<openssl rand -base64 48 生成>"
    Environment="DEEPSEEK_API_KEY=<你的Key>"
    Environment="CORS_ALLOWED_ORIGINS=http://[公网IP已隐藏]"

    ⚠️ 教训:EnvironmentFile 在不同 systemd 版本行为不一致。出现”格式全对但读不到”时,直接放弃文件方案改用 Environment= 硬编码,简单可靠。

三、环境文件排查动作

  1. 校验 /etc/blog/blog.env:确认无 Windows CRLF 换行、无多余空格与引号、权限 600、root 归属。

  2. 尝试追加末尾换行修复,systemd 仍无法识别,最终放弃文件读取方案(见上)。

  3. 排查命令参考:

    file /etc/blog/blog.env              # 文件类型与编码
    cat -A /etc/blog/blog.env            # 行尾出现 ^M 说明有 CRLF
    ls -l /etc/blog/blog.env             # 应为 -rw------- root root
    systemctl show blog | grep -i environment   # 验证变量是否被加载

四、管理员账号升级与网站配置入口

  1. 数据库升级角色:普通用户默认 role='USER',需在 DB 里升级为 ADMIN。中文用户名按 username 匹配会因终端/DB 字符集不一致失败(查询结果显示为 ????),按 id 更新最稳:

    docker exec blog-mysql mysql -ublog -p<业务密码> blog_db --default-character-set=utf8mb4 \
      -e "UPDATE \`user\` SET role='ADMIN' WHERE id=2;"
  2. 改完必须重新登录:JWT 里的角色是登录瞬间写入的,旧 token 仍是 USER,权限判断(@PreAuthorize("hasRole('ADMIN')"))不生效。退出 → 重新登录 → 拿到含 ADMIN 的新 token。

  3. 网站配置入口:管理员登录后 → 访问 /admin 管理面板 → 点击「网站配置」(路由 /admin/config,对应 SiteConfigAdmin.vue)。

  4. 验证:升级 + 重新登录后,公网全链路功能正常(注册/登录/发文/评论/点赞/AI 摘要/评论实时推送)。

五、开机自启与节省停机模式验证

  1. 开机自启确认:systemctl is-enabled docker nginx blog → docker/nginx 为 enabled,但 blog 初始为 disabled,需手动启用,否则实例重启后 Spring Boot 不会自动拉起:

    systemctl enable blog
    systemctl is-enabled blog   # 确认返回 enabled
  2. 节省停机模式实测:按量付费 + 节省停机模式,22:00 关机、次日开机,公网 IP 不变。

    • 原因:短期停机,原 IP 仍留在地址池未被占用,重启大概率复用。
    • ⚠️ 官方不保证保留:停机越久越可能被分配走。IP 一旦变化,需同步更新 Nginx server_name、CORS_ALLOWED_ORIGINS 环境变量,并重启 blog 服务。
    • 想要 IP 永不变 → 给实例绑定弹性公网 IP(EIP)。