sansong/deploy

三松礼品库 poc.cloudpure.cn 部署说明

本发布包用于 Linux + Nginx + Java 8，最终访问地址为 https://poc.cloudpure.cn。应用根目录固定为 /server/sansong；前端由 Nginx 同源托管，前端 API 基址为 /api，并原样代理到仅监听本机的 127.0.0.1:8080。

本次以 H2 文件库为主方案，客户 144 API 已启用，但发布包只有占位符，真实 API Key、H2 密码必须在服务器上通过安全渠道配置。

1. 运行要求与包内容

后端使用 Java 8、Spring Boot 2.7.18；服务器执行 java -version，确认主版本为 1.8。发布包包含：

• client-dist/：Vite 前端生产文件，使用同源 /api
• server/singsong-server.jar：Java 8 可执行 JAR
• config/application-prod-h2.yml.example、config/singsong-h2.env.example：H2 主方案
• config/application-prod.yml.example、config/singsong-postgresql.env.example：PostgreSQL 备选
• nginx/singsong.conf：仅属于 poc.cloudpure.cn 的独立站点配置
• systemd/singsong.service

发布包不包含 SSH 密码、真实客户 API Key、真实 H2/数据库密码、数据库文件、本地日志或源码。

2. DNS、上传与目录

先将 poc.cloudpure.cn 的 DNS 解析到目标服务器。上传时使用 SSH 用户与密钥，不要把密码写入脚本或文档：

scp singsong-release-poc.cloudpure.cn.zip <SSH用户>@<服务器地址>:/tmp/
ssh <SSH用户>@<服务器地址>
java -version
sudo useradd --system --home /server/sansong --shell /usr/sbin/nologin singsong 2>/dev/null || true
sudo mkdir -p /server/sansong/{releases,server,client-dist,config,exports,data}
sudo rm -rf /server/sansong/releases/new
sudo mkdir -p /server/sansong/releases/new
sudo unzip /tmp/singsong-release-poc.cloudpure.cn.zip -d /server/sansong/releases/new
sudo cp /server/sansong/releases/new/server/singsong-server.jar /server/sansong/server/
sudo rm -rf /server/sansong/client-dist/*
sudo cp -a /server/sansong/releases/new/client-dist/. /server/sansong/client-dist/
sudo chown -R singsong:singsong /server/sansong/server /server/sansong/config /server/sansong/exports /server/sansong/data
sudo chmod 750 /server/sansong/config /server/sansong/exports /server/sansong/data

3. H2 主方案与机密配置

H2 数据持久化在 /server/sansong/data。先复制示例，再在服务器本地生成强密码并编辑环境文件：

sudo cp /server/sansong/releases/new/config/application-prod-h2.yml.example /server/sansong/config/application-prod.yml
sudo cp /server/sansong/releases/new/config/singsong-h2.env.example /server/sansong/config/singsong.env
openssl rand -base64 36
sudo nano /server/sansong/config/singsong.env

将 H2_DB_PASSWORD 替换为刚生成的独立强密码；通过安全渠道取得真实客户 144 API Key 后，仅在服务器上的环境文件中填写：

CUSTOMER144_API_ENABLED=true
CUSTOMER144_API_KEY=<通过安全渠道取得的真实值>

不要把真实密码或 API Key 回填到发布目录、ZIP、Git 或命令行参数中。设置权限：

sudo chown singsong:singsong /server/sansong/config/application-prod.yml /server/sansong/config/singsong.env
sudo chmod 640 /server/sansong/config/application-prod.yml /server/sansong/config/singsong.env

PostgreSQL 备选

需要切换 PostgreSQL 时，安装并初始化 PostgreSQL 后，改用 application-prod.yml.example 与 singsong-postgresql.env.example。真实数据库密码仍只在服务器 /server/sansong/config/singsong.env 中填写。H2 是本次默认和优先部署方案。

4. 安装并启动 systemd

sudo cp /server/sansong/releases/new/systemd/singsong.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now singsong
sudo systemctl status singsong --no-pager

服务固定从 /server/sansong/server 启动，写目录仅开放 /server/sansong/data 和 /server/sansong/exports，8080 仅监听 127.0.0.1。

5. Nginx：先 HTTP，证书签发后再 HTTPS

包内配置只声明 server_name poc.cloudpure.cn，不要改动或覆盖现有 mc.cloudpure.cn 配置。建议使用独立文件名：

sudo cp /server/sansong/releases/new/nginx/singsong.conf /etc/nginx/conf.d/poc.cloudpure.cn.conf
sudo nginx -t
sudo systemctl reload nginx

5.1 申请证书前

默认启用的是临时 HTTP 站点，不引用任何证书文件，因此证书尚不存在时复制后执行 nginx -t 不会失败。开放 80 后验证：

curl -I http://poc.cloudpure.cn/
curl http://poc.cloudpure.cn/api/products/1

然后按服务器既有证书管理方式为 poc.cloudpure.cn 申请证书。不要在证书文件实际存在前启用 HTTPS 配置。

5.2 证书存在后

确认实际证书和私钥路径，再编辑 /etc/nginx/conf.d/poc.cloudpure.cn.conf：删除临时 HTTP server，取消文件中“启用 HTTPS 后”两段配置的注释，并按实际签发路径修改 ssl_certificate、ssl_certificate_key。随后：

sudo test -f /etc/letsencrypt/live/poc.cloudpure.cn/fullchain.pem
sudo test -f /etc/letsencrypt/live/poc.cloudpure.cn/privkey.pem
sudo nginx -t
sudo systemctl reload nginx
curl -I http://poc.cloudpure.cn/       # 应跳转 HTTPS
curl -I https://poc.cloudpure.cn/

proxy_pass http://127.0.0.1:8080; 末尾没有 /，会保留后端所需的 /api 前缀。

6. 防火墙与验证

安全组只开放 TCP 22（限制管理员源 IP）、80、443；不要开放 8080 或 5432：

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow from <管理员公网IP> to any port 22 proto tcp
sudo ufw deny 8080/tcp
sudo ufw deny 5432/tcp
sudo ufw enable
sudo ss -lntp | grep -E ':80|:443|:8080|:5432'

完成 HTTPS 后验证：

sudo systemctl restart singsong
sudo journalctl -u singsong -n 100 --no-pager
curl -I http://127.0.0.1:8080/api/products/1
curl -I https://poc.cloudpure.cn/
curl https://poc.cloudpure.cn/api/products/1
sudo -u singsong test -w /server/sansong/data && echo H2目录可写
sudo -u singsong test -w /server/sansong/exports && echo 导出目录可写

预期：首页成功加载，API 返回 JSON；浏览器访问 https://poc.cloudpure.cn，验证搜索、详情、导出和下载。CORS 固定为 https://poc.cloudpure.cn。

7. 常见故障

• UnsupportedClassVersionError：确认服务器 Java 主版本为 1.8。
• H2 启动失败：检查 H2_DB_PASSWORD 是否已替换、/server/sansong/data 是否可写。
• 客户 144 API 调用失败：确认 CUSTOMER144_API_ENABLED=true，并在服务器环境文件中安全填写真实 Key。
• Nginx 502：检查 singsong 服务及 127.0.0.1:8080。
• API 404：确认 proxy_pass 末尾无 /。
• nginx -t 报证书不存在：恢复临时 HTTP 配置，证书签发并确认文件存在后再启用 HTTPS 段。
• 页面刷新 404：确认 try_files $uri $uri/ /index.html 生效。
• 权限错误：检查 /server/sansong/{data,exports,config} 的所有者和权限。

8. H2 备份、升级与回滚

复制 H2 数据前必须停服务：

STAMP=$(date +%Y%m%d%H%M%S)
sudo systemctl stop singsong
sudo mkdir -p /server/sansong/releases/backup-$STAMP
sudo cp /server/sansong/server/singsong-server.jar /server/sansong/releases/backup-$STAMP/
sudo cp -a /server/sansong/client-dist /server/sansong/releases/backup-$STAMP/
sudo cp -a /server/sansong/data /server/sansong/releases/backup-$STAMP/
sudo cp /server/sansong/releases/new/server/singsong-server.jar /server/sansong/server/
sudo rm -rf /server/sansong/client-dist/*
sudo cp -a /server/sansong/releases/new/client-dist/. /server/sansong/client-dist/
sudo systemctl start singsong

回滚时停止服务，恢复备份中的 JAR、client-dist 和需要恢复的 data 后再启动。PostgreSQL 备选方案应使用 pg_dump/恢复流程，不复制运行中的数据库目录。