添加部署说明文档

2026-03-22 21:18:05 +08:00 · 2026-03-22 21:18:05 +08:00 · 677916a294
--- a/DEPLOY.md
+++ b/DEPLOY.md
@ -0,0 +1,243 @@
+# 呼籁官网 部署说明
+
+## 项目结构
+
+```
+hulai-website/       # 官网前端（Nuxt 3 SSR）
+hulai-admin-web/     # 管理后台前端（Vue 3 + Element Plus）
+hulai-admin-api/     # 管理后台后端（FastAPI + MySQL）
+```
+
+## 环境要求
+
+- Node.js >= 20
+- pnpm（`npm install -g pnpm`）
+- pm2（`npm install -g pm2`）
+- Python >= 3.12
+- MySQL 8.0
+- Nginx
+
+## 端口规划
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| hulai-admin-api | 9003 | FastAPI 后端（uvicorn） |
+| hulai-admin-web | 9001 | 管理后台前端（nginx 静态） |
+| hulai-website | 9002 | 官网（nginx 反代 → Nuxt SSR 3001） |
+| Nuxt SSR | 3001 | 内部端口，pm2 管理 |
+
+## 一、后端部署（hulai-admin-api）
+
+### 1. 创建数据库
+
+```sql
+CREATE DATABASE hulai_gw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+### 2. 安装依赖
+
+```bash
+cd hulai-admin-api
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+# 注意：如果 bcrypt 报错，降级：pip install bcrypt==4.0.1
+```
+
+### 3. 配置 .env
+
+```bash
+cat > .env << 'EOF'
+DATABASE_URL=mysql+pymysql://root:密码@localhost:3306/hulai_gw?charset=utf8mb4
+JWT_SECRET_KEY=生产环境请用强随机密钥
+JWT_ALGORITHM=HS256
+JWT_EXPIRE_MINUTES=480
+NUXT_DATA_PATH=/opt/gw/hulai-website/data
+NUXT_PROJECT_PATH=/opt/gw/hulai-website
+UPLOAD_DIR=/opt/gw/hulai-website/public/images
+EOF
+```
+
+### 4. 初始化数据库表
+
+```bash
+source venv/bin/activate
+python3 -c '
+from app.database import engine, Base
+from app.models import *
+Base.metadata.create_all(bind=engine)
+print("Tables created")
+'
+```
+
+### 5. 创建管理员账号
+
+```bash
+python3 -c '
+from app.database import SessionLocal
+from app.models.user import AdminUser
+from app.auth import hash_password
+db = SessionLocal()
+user = AdminUser(username="admin", password_hash=hash_password("Admin@123456"), role="admin", is_active=True)
+db.add(user); db.commit(); db.close()
+print("Admin created")
+'
+```
+
+### 6. 启动服务
+
+```bash
+source venv/bin/activate
+ENV=development nohup uvicorn app.main:app --host 0.0.0.0 --port 9003 > /tmp/gw-api.log 2>&1 &
+```
+
+### 7. 导入现有数据（可选）
+
+如果 `hulai-website/data/` 下有 JSON 数据文件，可用脚本导入到数据库：
+
+```bash
+python3 scripts/import_remaining.py
+python3 scripts/import_products.py
+```
+
+## 二、管理后台前端（hulai-admin-web）
+
+### 1. 安装依赖 & 构建
+
+```bash
+cd hulai-admin-web
+npm install --legacy-peer-deps
+npm run build
+```
+
+构建产物在 `dist/` 目录。
+
+## 三、官网前端（hulai-website）
+
+### 1. 安装依赖 & 构建
+
+```bash
+cd hulai-website
+pnpm install
+pnpm build
+```
+
+### 2. 用 pm2 启动 SSR 服务
+
+```bash
+PORT=3001 pm2 start .output/server/index.mjs --name gw-website
+pm2 save
+pm2 startup  # 设置开机自启
+```
+
+## 四、Nginx 配置
+
+```nginx
+# 管理后台 - 端口 9001
+server {
+    listen 9001;
+    server_name _;
+    root /opt/gw/hulai-admin-web/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:9003;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /images/ {
+        alias /opt/gw/hulai-website/public/images/;
+    }
+}
+
+# 官网 - 端口 9002
+server {
+    listen 9002;
+    server_name _;
+
+    location / {
+        proxy_pass http://127.0.0.1:3001;
+        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;
+    }
+}
+```
+
+```bash
+# 放到 sites-available 并启用
+cp gw.conf /etc/nginx/sites-available/gw
+ln -sf /etc/nginx/sites-available/gw /etc/nginx/sites-enabled/gw
+nginx -t && nginx -s reload
+```
+
+## 五、自动导出 & 重建
+
+管理后台编辑内容保存后，系统自动：
+1. 将数据库数据导出为 JSON 文件（写入 `hulai-website/data/`）
+2. 写入触发文件 `/tmp/gw-rebuild-trigger`
+3. cron 每分钟检测触发文件 → 执行 `pnpm build` → `pm2 restart`
+
+### 设置 cron
+
+```bash
+chmod +x /opt/gw/hulai-admin-api/rebuild.sh
+(crontab -l 2>/dev/null; echo '* * * * * /opt/gw/hulai-admin-api/rebuild.sh') | crontab -
+```
+
+### 手动触发重建
+
+```bash
+/opt/gw/hulai-admin-api/rebuild.sh
+```
+
+### 查看重建日志
+
+```bash
+tail -f /tmp/gw-rebuild.log
+```
+
+## 六、防火墙
+
+```bash
+ufw allow 9001/tcp comment 'GW admin-web'
+ufw allow 9002/tcp comment 'GW website'
+ufw reload
+```
+
+## 七、日常运维
+
+```bash
+# 查看 API 日志
+tail -f /tmp/gw-api.log
+
+# 重启 API
+kill $(ps aux | grep 'uvicorn app.main' | grep -v grep | awk '{print $2}')
+cd /opt/gw/hulai-admin-api && source venv/bin/activate
+ENV=development nohup uvicorn app.main:app --host 0.0.0.0 --port 9003 > /tmp/gw-api.log 2>&1 &
+
+# 重启官网
+pm2 restart gw-website
+
+# 重建官网
+cd /opt/gw/hulai-website && pnpm build && pm2 restart gw-website
+
+# 查看 pm2 状态
+pm2 list
+pm2 logs gw-website
+```
+
+## 八、测试环境信息
+
+| 项目 | 地址 |
+|------|------|
+| 管理后台 | http://1.182.108.58:9001 |
+| 官网 | http://1.182.108.58:9002 |
+| API 健康检查 | http://1.182.108.58:9003/api/health |
+| 管理员账号 | admin / Admin@123456 |