chengshishouce/city-manual/docs/CLOUD_DEPLOYMENT.md

# 云服务器部署指南

## 目标服务器

- **主机:** cssc.datalibstar.com
- **用户:** mashen
- **项目路径:** /root/.openclaw/workspace/city-manual

---

## 部署前准备

### 1. 解决 SSH 连接问题

当前 SSH 认证失败，需要：

**方案 A: 使用密码登录**
```bash
# 在本地测试
ssh mashen@cssc.datalibstar.com
# 输入密码：825670@MashenClaw
```

**方案 B: 配置 SSH 密钥**
```bash
# 在服务器上添加公钥
ssh-copy-id mashen@cssc.datalibstar.com

# 或手动添加
cat ~/.ssh/id_ed25519.pub | ssh mashen@cssc.datalibstar.com "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
```

### 2. 服务器环境要求

**必需软件：**
- Python 3.8+
- Node.js 16+
- PostgreSQL 12+
- Nginx
- Gunicorn

**检查命令：**
```bash
python3 --version
node --version
psql --version
nginx -v
```

---

## 部署步骤

### 步骤 1: 克隆项目

```bash
# SSH 到服务器
ssh mashen@cssc.datalibstar.com

# 进入工作目录
cd /root/.openclaw/workspace

# 克隆最新代码
git clone http://10.2.0.100:8989/mashen/chengshishouce.git city-manual-temp
cd city-manual-temp
git checkout master
```

### 步骤 2: 安装后端依赖

```bash
cd /root/.openclaw/workspace/city-manual-temp/backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
pip install gunicorn
```

### 步骤 3: 配置环境变量

```bash
cd /root/.openclaw/workspace/city-manual-temp

# 创建 .env 文件
cat > .env << EOF
# Django 配置
DJANGO_SETTINGS_MODULE=config.settings.production
DJANGO_SECRET_KEY=your-secret-key-change-this
DEBUG=False
ALLOWED_HOSTS=cssc.datalibstar.com,127.0.0.1,localhost

# 数据库配置
DATABASE_URL=postgres://coder:825670wl@10.2.0.100:5432/cssc

# 媒体文件
MEDIA_ROOT=/root/.openclaw/workspace/city-manual-temp/backend/media
STATIC_ROOT=/root/.openclaw/workspace/city-manual-temp/backend/static
EOF
```

### 步骤 4: 数据库迁移

```bash
cd /root/.openclaw/workspace/city-manual-temp/backend
source ../venv/bin/activate

# 执行迁移
python manage.py migrate

# 收集静态文件
python manage.py collectstatic --noinput

# 创建超级用户（可选）
python manage.py createsuperuser
```

### 步骤 5: 配置 Gunicorn

```bash
# 创建 systemd 服务文件
sudo cat > /etc/systemd/system/city-manual.service << 'EOF'
[Unit]
Description=City Manual Gunicorn Service
After=network.target

[Service]
User=root
Group=root
WorkingDirectory=/root/.openclaw/workspace/city-manual-temp/backend
ExecStart=/root/.openclaw/workspace/city-manual-temp/backend/venv/bin/gunicorn \
    --access-logfile - \
    --workers 3 \
    --bind unix:/run/city-manual.sock \
    city_manual.wsgi:application
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable city-manual
sudo systemctl start city-manual

# 检查状态
sudo systemctl status city-manual
```

### 步骤 6: 配置 Nginx

```bash
# 创建 Nginx 配置
sudo cat > /etc/nginx/sites-available/city-manual << 'EOF'
server {
    listen 80;
    server_name cssc.datalibstar.com;

    # 日志
    access_log /var/log/nginx/city-manual-access.log;
    error_log /var/log/nginx/city-manual-error.log;

    # 静态文件
    location /static/ {
        alias /root/.openclaw/workspace/city-manual-temp/backend/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 媒体文件
    location /media/ {
        alias /root/.openclaw/workspace/city-manual-temp/backend/media/;
        expires 7d;
    }

    # Django 应用
    location / {
        include proxy_params;
        proxy_pass http://unix:/run/city-manual.sock;
        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;
    }

    # 客户端最大上传大小
    client_max_body_size 10M;
}
EOF

# 启用配置
sudo ln -sf /etc/nginx/sites-available/city-manual /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重载 Nginx
sudo systemctl reload nginx
```

### 步骤 7: 配置防火墙

```bash
# 开放 HTTP 端口
sudo ufw allow 80/tcp

# 开放 HTTPS 端口（如果启用 SSL）
sudo ufw allow 443/tcp

# 检查防火墙状态
sudo ufw status
```

### 步骤 8: 部署前端（可选）

如果使用前后端分离部署：

```bash
cd /root/.openclaw/workspace/city-manual-temp/frontend

# 安装依赖
npm install

# 构建生产版本
npm run build

# 配置 Nginx 服务构建文件
# （需要额外配置 Nginx 路由）
```

### 步骤 9: 验证部署

```bash
# 检查 Gunicorn 状态
sudo systemctl status city-manual

# 检查 Nginx 状态
sudo systemctl status nginx

# 测试访问
curl http://cssc.datalibstar.com/
curl http://cssc.datalibstar.com/admin/

# 查看日志
sudo tail -f /var/log/nginx/city-manual-access.log
sudo tail -f /var/log/nginx/city-manual-error.log
```

---

## 自动化部署脚本

创建 `deploy.sh` 脚本：

```bash
#!/bin/bash
set -e

echo "🚀 开始部署城市手册..."

PROJECT_DIR="/root/.openclaw/workspace/city-manual"
VENV_DIR="$PROJECT_DIR/backend/venv"

# 1. 拉取最新代码
cd $PROJECT_DIR
git pull origin master

# 2. 安装依赖
source $VENV_DIR/bin/activate
pip install -r requirements.txt -q

# 3. 数据库迁移
cd $PROJECT_DIR/backend
python manage.py migrate --noinput

# 4. 收集静态文件
python manage.py collectstatic --noinput

# 5. 重启 Gunicorn
sudo systemctl restart city-manual

# 6. 检查状态
sleep 2
if sudo systemctl is-active --quiet city-manual; then
    echo "✅ 部署成功！"
    echo "📍 访问地址：http://cssc.datalibstar.com"
else
    echo "❌ 部署失败，请检查日志"
    exit 1
fi
```

使用：
```bash
chmod +x deploy.sh
./deploy.sh
```

---

## HTTPS 配置（推荐）

### 使用 Let's Encrypt

```bash
# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d cssc.datalibstar.com

# 自动续期
sudo certbot renew --dry-run
```

### 配置自动 HTTPS 重定向

Nginx 配置会自动添加 301 重定向。

---

## 监控和维护

### 日志查看

```bash
# Nginx 日志
sudo tail -f /var/log/nginx/city-manual-access.log
sudo tail -f /var/log/nginx/city-manual-error.log

# Gunicorn 日志
sudo journalctl -u city-manual -f
```

### 性能监控

```bash
# 查看进程
ps aux | grep gunicorn

# 查看连接
sudo netstat -nltp | grep city-manual

# 查看资源使用
htop
```

### 备份数据库

```bash
# 备份
pg_dump -h 10.2.0.100 -U coder cssc > backup_$(date +%Y%m%d).sql

# 恢复
psql -h 10.2.0.100 -U coder cssc < backup_20260412.sql
```

---

## 故障排除

### 问题 1: Gunicorn 启动失败

```bash
# 查看详细错误
sudo journalctl -u city-manual -n 50

# 检查端口占用
sudo lsof -i :8000

# 手动测试
cd /root/.openclaw/workspace/city-manual/backend
source venv/bin/activate
python manage.py runserver
```

### 问题 2: Nginx 502 Bad Gateway

```bash
# 检查 Gunicorn socket
ls -la /run/city-manual.sock

# 检查权限
sudo chmod 666 /run/city-manual.sock

# 重启服务
sudo systemctl restart city-manual
sudo systemctl restart nginx
```

### 问题 3: 静态文件 404

```bash
# 重新收集
cd /root/.openclaw/workspace/city-manual/backend
source venv/bin/activate
python manage.py collectstatic --noinput

# 检查 Nginx 配置路径
sudo nginx -t
```

### 问题 4: 数据库连接失败

```bash
# 测试连接
psql -h 10.2.0.100 -U coder -d cssc

# 检查 .env 配置
cat /root/.openclaw/workspace/city-manual/.env
```

---

## 回滚方案

```bash
# 1. 切换到上一个版本
cd /root/.openclaw/workspace/city-manual
git checkout <previous-commit>

# 2. 重新部署
./deploy.sh

# 3. 验证
curl http://cssc.datalibstar.com/
```

---

## 部署检查清单

- [ ] SSH 可以正常连接
- [ ] Python 和 Node.js 版本正确
- [ ] PostgreSQL 可连接
- [ ] 代码已拉取到最新
- [ ] 依赖已安装
- [ ] 数据库迁移完成
- [ ] 静态文件已收集
- [ ] Gunicorn 服务运行正常
- [ ] Nginx 配置正确
- [ ] 防火墙已配置
- [ ] 可以通过浏览器访问
- [ ] Admin 后台可以登录
- [ ] 日志正常无错误

---

## 参考链接

- [Django 部署文档](https://docs.djangoproject.com/en/stable/howto/deployment/)
- [Gunicorn 文档](https://docs.gunicorn.org/en/stable/)
- [Nginx 配置最佳实践](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/)

---

## 版本信息

- **文档版本:** 1.0
- **创建日期:** 2026-04-12
- **项目版本:** 2026.4.12
- **作者:** 码神 ⚡