chengshishouce/city-manual/docs/CLOUD_DEPLOYMENT.md

云服务器部署指南

目标服务器

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

---

部署前准备

1. 解决 SSH 连接问题

当前 SSH 认证失败，需要：

方案 A: 使用密码登录

# 在本地测试
ssh mashen@cssc.datalibstar.com
# 输入密码：825670@MashenClaw

方案 B: 配置 SSH 密钥

# 在服务器上添加公钥
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

检查命令：

python3 --version
node --version
psql --version
nginx -v

---

部署步骤

步骤 1: 克隆项目

# 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: 安装后端依赖

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: 配置环境变量

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: 数据库迁移

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

# 创建 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

# 创建 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: 配置防火墙

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

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

# 检查防火墙状态
sudo ufw status

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

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

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

# 安装依赖
npm install

# 构建生产版本
npm run build

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

步骤 9: 验证部署

# 检查 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 脚本：

#!/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

使用：

chmod +x deploy.sh
./deploy.sh

---

HTTPS 配置（推荐）

使用 Let's Encrypt

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

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

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

配置自动 HTTPS 重定向

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

---

监控和维护

日志查看

# 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

性能监控

# 查看进程
ps aux | grep gunicorn

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

# 查看资源使用
htop

备份数据库

# 备份
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 启动失败

# 查看详细错误
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

# 检查 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

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

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

问题 4: 数据库连接失败

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

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

---

回滚方案

# 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 部署文档
• Gunicorn 文档
• Nginx 配置最佳实践

---

版本信息

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