chengshishouce/DEPLOYMENT.md

# 城市手册项目部署指南

## 部署前准备

### 1. 环境要求

- Python 3.11+
- Node.js 18+
- PostgreSQL 15+
- Docker & Docker Compose（可选）
- Nginx（可选）

### 2. 数据库配置

```bash
# 创建数据库
createdb citywiki

# 或使用 Docker
docker run -d \
  --name citywiki-db \
  -e POSTGRES_DB=citywiki \
  -e POSTGRES_USER=citywiki \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  postgres:15-alpine
```

### 3. 环境变量配置

复制 `.env.example` 到 `.env` 并配置：

```env
# Django Settings
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_DEBUG=False

# Database
DB_NAME=citywiki
DB_USER=citywiki
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432

# Allowed Hosts
ALLOWED_HOSTS=localhost,yourdomain.com

# CORS
CORS_ALLOWED_ORIGINS=http://localhost,https://yourdomain.com

# Email（可选）
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@example.com
EMAIL_HOST_PASSWORD=your-email-password
```

---

## 部署方式

### 方式一：Docker Compose（推荐）

#### 1. 构建镜像

```bash
docker-compose build
```

#### 2. 启动服务

```bash
docker-compose up -d
```

#### 3. 运行迁移

```bash
docker-compose exec backend python manage.py migrate
```

#### 4. 创建超级用户

```bash
docker-compose exec backend python manage.py createsuperuser
```

#### 5. 查看日志

```bash
docker-compose logs -f
```

#### 6. 停止服务

```bash
docker-compose down
```

---

### 方式二：手动部署

#### 后端部署

```bash
cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 运行迁移
python manage.py migrate

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

# 创建超级用户
python manage.py createsuperuser

# 启动服务（生产环境）
gunicorn config.wsgi:application --bind 0.0.0.0:8000 --workers 3
```

#### 前端部署

```bash
cd frontend

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 构建
npm run build
```

---

### 方式三：Nginx 部署

#### Nginx 配置

```nginx
server {
    listen 80;
    server_name yourdomain.com;

    # 前端静态文件
    location / {
        root /path/to/frontend/build;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # GraphQL 代理
    location /graphql/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态文件
    location /static/ {
        alias /path/to/backend/staticfiles/;
    }

    # 媒体文件
    location /media/ {
        alias /path/to/backend/media/;
    }
}
```

#### 启动服务

```bash
# 启动后端
cd backend
source venv/bin/activate
gunicorn config.wsgi:application --bind 127.0.0.1:8000 --workers 3

# 启动 Nginx
sudo nginx -t
sudo systemctl restart nginx
```

---

## 生产环境配置

### 1. Django 配置

```python
# config/settings/prod.py
DEBUG = False

# 安全设置
SECURE_BROWSER_XSS_FILTER = True
SECURE_CONTENT_TYPE_NOSNIFF = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SECURE_SSL_REDIRECT = True

# 允许的主机
ALLOWED_HOSTS = ['yourdomain.com']

# 数据库（使用 Unix socket 更快）
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'citywiki',
        'USER': 'citywiki',
        'PASSWORD': 'your_password',
        'HOST': '/var/run/postgresql',
        'PORT': '',
    }
}
```

### 2. Gunicorn 配置

创建 `gunicorn.conf.py`：

```python
bind = "127.0.0.1:8000"
workers = 3
worker_class = "sync"
worker_connections = 1000
max_requests = 1000
max_requests_jitter = 50
timeout = 30
keepalive = 2
```

启动 Gunicorn：

```bash
gunicorn -c gunicorn.conf.py config.wsgi:application
```

### 3. Systemd 服务（自动重启）

创建 `/etc/systemd/system/citywiki.service`：

```ini
[Unit]
Description=CityWiki Django App
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/backend
ExecStart=/path/to/backend/venv/bin/gunicorn -c gunicorn.conf.py config.wsgi:application
Restart=always

[Install]
WantedBy=multi-user.target
```

启动服务：

```bash
sudo systemctl daemon-reload
sudo systemctl start citywiki
sudo systemctl enable citywiki
```

---

## 监控和日志

### 1. Django 日志配置

```python
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': '/var/log/citywiki/django.log',
        },
    },
    'loggers': {
        'django': {
            'handlers': ['file'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}
```

### 2. Nginx 日志

```nginx
access_log /var/log/nginx/citywiki_access.log;
error_log /var/log/nginx/citywiki_error.log;
```

---

## 数据备份

### PostgreSQL 备份

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

# 恢复
psql -U citywiki citywiki < backup_20260409.sql
```

### 媒体文件备份

```bash
rsync -avz /path/to/backend/media/ /backup/media/
```

---

## HTTPS 配置（Let's Encrypt）

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

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

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

---

## 性能优化

### 1. 数据库优化

```sql
-- 添加索引
CREATE INDEX idx_articles_region ON articles(region_id);
CREATE INDEX idx_articles_status ON articles(publish_status);
CREATE INDEX idx_services_region ON featured_services(region_id);
CREATE INDEX idx_services_status ON featured_services(publish_status);
CREATE INDEX idx_comments_target ON comments(target_type, target_id);
```

### 2. 缓存（Redis）

```bash
# 安装 Redis
sudo apt-get install redis-server
```

配置 Django 使用 Redis：

```python
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379/1',
    }
}
```

### 3. CDN 加速

使用 Cloudflare 或阿里云 CDN 加速静态文件访问。

---

## 故障排查

### 1. 数据库连接失败

```bash
# 检查 PostgreSQL 是否运行
sudo systemctl status postgresql

# 检查端口
sudo netstat -tuln | grep 5432
```

### 2. 静态文件 404

```bash
# 重新收集静态文件
cd backend
python manage.py collectstatic --noinput
```

### 3. Nginx 502 Bad Gateway

```bash
# 检查 Django 是否运行
ps aux | grep gunicorn

# 重启 Django
sudo systemctl restart citywiki
```

---

## 更新部署

```bash
# 拉取最新代码
git pull origin master

# 后端更新
cd backend
source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic --noinput
sudo systemctl restart citywiki

# 前端更新
cd frontend
npm install
npm run build
sudo systemctl restart nginx
```

---

## 安全检查清单

- [ ] 更改 Django SECRET_KEY
- [ ] 设置 DEBUG=False
- [ ] 配置 ALLOWED_HOSTS
- [ ] 启用 HTTPS
- [ ] 配置数据库防火墙
- [ ] 定期备份数据
- [ ] 更新依赖包
- [ ] 监控日志文件
- [ ] 配置 fail2ban
- [ ] 定期安全审计

---

## 参考资料

- [Django 部署指南](https://docs.djangoproject.com/en/4.2/howto/deployment/)
- [Gunicorn 文档](https://docs.gunicorn.org/en/stable/)
- [Nginx 文档](https://nginx.org/en/docs/)
- [Docker Compose 文档](https://docs.docker.com/compose/)