# 三松礼品库 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 用户与密钥，不要把密码写入脚本或文档：

```bash
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`。先复制示例，再在服务器本地生成强密码并编辑环境文件：

```bash
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 后，仅在服务器上的环境文件中填写：

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

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

```bash
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

```bash
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` 配置。建议使用独立文件名：

```bash
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 后验证：

```bash
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`。随后：

```bash
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：

```bash
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 后验证：

```bash
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 数据前必须停服务：

```bash
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`/恢复流程，不复制运行中的数据库目录。