From 6da6dba3f903d34e5ca08378c8fc317ecebe41e4 Mon Sep 17 00:00:00 2001
From: Developer <developer@rwadurian.com>
Date: Mon, 1 Dec 2025 21:21:25 -0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E5=A4=8D=E9=83=A8=E7=BD=B2?=
 =?UTF-8?q?=E6=AD=A5=E9=AA=A4=E9=A1=BA=E5=BA=8F=EF=BC=8CSSL=E8=AF=81?=
 =?UTF-8?q?=E4=B9=A6=E8=8E=B7=E5=8F=96=E4=BC=98=E5=85=88=E4=BA=8E=E7=AB=99?=
 =?UTF-8?q?=E7=82=B9=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

对于全新系统部署，必须先获取 Let's Encrypt 证书，
然后才能配置引用这些证书的 Nginx 站点配置。

修改内容：
- 将 SSL 证书获取移到步骤 3（配置站点之前）
- 提供 standalone 和 webroot 两种证书获取方式
- 添加清晰的步骤注释说明
- 移除不需要的 /etc/nginx/ssl 目录创建

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../identity-service/docs/DEPLOYMENT_GUIDE.md | 82 +++++++++++++------
 1 file changed, 55 insertions(+), 27 deletions(-)

diff --git a/backend/services/identity-service/docs/DEPLOYMENT_GUIDE.md b/backend/services/identity-service/docs/DEPLOYMENT_GUIDE.md
index cb4f3640..8660162c 100644
--- a/backend/services/identity-service/docs/DEPLOYMENT_GUIDE.md
+++ b/backend/services/identity-service/docs/DEPLOYMENT_GUIDE.md
@@ -929,53 +929,81 @@ WALLET_ENCRYPTION_SALT=your_wallet_encryption_salt
 ### 6.1 Nginx + MPC 服务器 (192.168.1.100) 配置
 
 ```bash
-# 1. 安装 Nginx
-apt update && apt install -y nginx
+# ============================================
+# 步骤 1: 安装 Nginx 和 Let's Encrypt
+# ============================================
+apt update && apt install -y nginx certbot python3-certbot-nginx
 
-# 2. 创建目录结构
+# ============================================
+# 步骤 2: 创建目录结构
+# ============================================
 mkdir -p /etc/nginx/sites-available
 mkdir -p /etc/nginx/sites-enabled
 mkdir -p /etc/nginx/snippets
-mkdir -p /etc/nginx/ssl
 
-# 3. 复制配置文件
+# ============================================
+# 步骤 3: 获取 SSL 证书 (必须在配置 HTTPS 站点之前)
+# ============================================
+# 重要：在全新系统上，必须先获取证书，否则 Nginx 配置引用证书路径会报错
+
+# 方式 A: 使用 standalone 模式 (推荐用于首次部署)
+# 临时停止 Nginx (如果正在运行)
+systemctl stop nginx
+# 获取证书
+certbot certonly --standalone -d rwaapi.szaiai.com
+# 证书保存位置:
+#   /etc/letsencrypt/live/rwaapi.szaiai.com/fullchain.pem  (完整证书链)
+#   /etc/letsencrypt/live/rwaapi.szaiai.com/privkey.pem    (私钥)
+
+# 方式 B: 使用 webroot 模式 (需要先配置 HTTP 站点)
+# 1. 先配置一个简单的 HTTP 站点 (不含 SSL)
+# 2. certbot certonly --webroot -w /var/www/html -d rwaapi.szaiai.com
+
+# ============================================
+# 步骤 4: 复制 Nginx 配置文件
+# ============================================
 # 将上面的配置文件复制到对应目录:
 # - nginx.conf → /etc/nginx/nginx.conf
 # - proxy-params.conf → /etc/nginx/snippets/proxy-params.conf
 # - ssl-params.conf → /etc/nginx/snippets/ssl-params.conf
 # - rwaapi.szaiai.com.conf → /etc/nginx/sites-available/rwaapi.szaiai.com.conf
 
-# 4. 启用站点 (创建软链接)
-ln -s /etc/nginx/sites-available/rwaapi.szaiai.com.conf /etc/nginx/sites-enabled/
-
-# 5. 禁用默认站点 (如果存在)
+# ============================================
+# 步骤 5: 启用站点
+# ============================================
+# 禁用默认站点 (如果存在)
 rm -f /etc/nginx/sites-enabled/default
 
-# 6. 安装 SSL 证书 (Let's Encrypt)
-apt install -y certbot python3-certbot-nginx
-# 获取证书 (证书自动保存到 /etc/letsencrypt/live/rwaapi.szaiai.com/)
-certbot certonly --nginx -d rwaapi.szaiai.com
-# 证书文件:
-#   /etc/letsencrypt/live/rwaapi.szaiai.com/fullchain.pem  (完整证书链)
-#   /etc/letsencrypt/live/rwaapi.szaiai.com/privkey.pem    (私钥)
-# 无需创建软链接，Nginx 配置直接引用 Let's Encrypt 路径
+# 创建软链接启用站点
+ln -s /etc/nginx/sites-available/rwaapi.szaiai.com.conf /etc/nginx/sites-enabled/
 
-# 设置自动续期 (Let's Encrypt 证书有效期 90 天)
-# certbot 已自动配置 systemd timer，可通过以下命令验证:
-systemctl list-timers | grep certbot
-# 或手动测试续期:
-certbot renew --dry-run
-
-# 7. 测试配置
+# ============================================
+# 步骤 6: 测试并启动 Nginx
+# ============================================
+# 测试配置 (此时证书已存在，不会报错)
 nginx -t
 
-# 8. 重启 Nginx
-systemctl restart nginx
+# 启动 Nginx
+systemctl start nginx
 systemctl enable nginx
 
-# 9. 站点管理命令
+# ============================================
+# 步骤 7: 配置证书自动续期
+# ============================================
+# Let's Encrypt 证书有效期 90 天，certbot 已自动配置 systemd timer
+# 验证自动续期任务:
+systemctl list-timers | grep certbot
+
+# 手动测试续期 (不会实际续期，只是测试流程):
+certbot renew --dry-run
+
+# ============================================
+# 站点管理命令 (日常运维)
+# ============================================
 # 禁用站点: rm /etc/nginx/sites-enabled/rwaapi.szaiai.com.conf && nginx -s reload
 # 启用站点: ln -s /etc/nginx/sites-available/rwaapi.szaiai.com.conf /etc/nginx/sites-enabled/ && nginx -s reload
+# 重新加载: nginx -s reload
+# 查看状态: systemctl status nginx
 ```
 
 ### 6.2 后端服务器 (192.168.1.111) 配置