docs: 添加部署指南和更新 README

- DEPLOYMENT.md（详细部署指南） - 更新 README.md（项目信息、功能特性、快速开始） - 添加 Docker 部署说明 - 添加文档链接
2026-04-09 13:50:11 +00:00
parent e627e3f579
commit 6f3b74639c
2 changed files with 532 additions and 42 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -0,0 +1,473 @@
+# 城市手册项目部署指南
+
+## 部署前准备
+
+### 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/)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,22 @@
 # React + Django Full-Stack Project

-## Tech Stack
+## 项目信息
+
+**项目名称：** 城市手册（CityWiki）  
+**项目定位：** 地方志兼本地生活服务平台  
+**技术栈：** React + Django + PostgreSQL + Docker
+
+## 功能特性
+
+- ✅ 用户认证系统（注册、登录、JWT）
+- ✅ 版块层级管理（省→市→县→乡镇→村）
+- ✅ 文章管理（创建、审核、发布）
+- ✅ 特色服务（衣食住行娱乐旅游文化）
+- ✅ 交互功能（评论、评分、点赞、收藏）
+- ✅ 版主管理（申请、权限、审核）
+- ✅ 内容审核流程（版主初审 + AI 审核）
+
+## 技术栈

 ### Backend
 - Django 4.2
@@ -11,13 +27,13 @@

 ### Frontend
 - React 18 (Create React App)
- MobX (state management)
+- MobX (状态管理)
 - styled-components (CSS-in-JS)
 - React Router

 ### Deployment
 - Docker & Docker Compose
- Nginx (reverse proxy)
+- Nginx (反向代理)

 ## Project Structure

@@ -39,85 +55,86 @@
 └── .env.example
 ```

-## Setup Instructions
+## 快速开始

-### 1. Environment Variables
+### 1. 克隆项目

-Copy `.env.example` to `.env` and configure:
+```bash
+git clone http://10.2.0.100:8989/mashen/chengshishouce.git
+cd chengshishouce
+```
+
+### 2. 环境变量配置

 ```bash
 cp .env.example .env
+# 编辑 .env 文件，配置数据库和其他设置
 ```

-Update the following variables:
- `DJANGO_SECRET_KEY` - Generate a secure secret key
- Database credentials (DB_NAME, DB_USER, DB_PASSWORD)
- `ALLOWED_HOSTS` - Add your domain(s)
-
-### 2. PostgreSQL Configuration
-
-If using external PostgreSQL (already deployed):
-
-Update `.env` with your database credentials:
-```env
-DB_HOST=your-db-host
-DB_PORT=5432
-DB_NAME=your_database_name
-DB_USER=your_database_user
-DB_PASSWORD=your_database_password
-```
-
-If using Docker PostgreSQL:
-
-The default values in `docker-compose.yml` will work.
-
-### 3. Backend Setup
+### 3. 后端启动

 ```bash
 cd backend

-# Create virtual environment
+# 创建虚拟环境
 python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
+source venv/bin/activate  # Windows: venv\Scripts\activate

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

-# Run migrations
+# 运行迁移
 python manage.py migrate

-# Create superuser
+# 创建超级用户
 python manage.py createsuperuser

-# Run development server
+# 启动开发服务器
 python manage.py runserver
 ```

-### 4. Frontend Setup
+### 4. 前端启动

 ```bash
 cd frontend

-# Install dependencies
+# 安装依赖
 npm install

-# Start development server
+# 启动开发服务器
 npm start
 ```

-### 5. Docker Deployment
+### 5. 访问应用
+
+- 前端：http://localhost:3000
+- 后端 API：http://localhost:8000
+- GraphQL：http://localhost:8000/graphql
+- Django Admin：http://localhost:8000/admin
+
+## Docker 部署

 ```bash
-# Build and start all services
+# 构建并启动所有服务
 docker-compose up -d

-# View logs
+# 查看日志
 docker-compose logs -f

-# Stop services
+# 停止服务
 docker-compose down
 ```

+详细部署指南请参考 [DEPLOYMENT.md](./DEPLOYMENT.md)
+
+## 项目文档
+
+- [需求文档](./城市手册需求文档.md) - 项目需求说明
+- [实施计划](./REQUIREMENTS_IMPLEMENTATION.md) - 需求实施进度
+- [部署指南](./DEPLOYMENT.md) - 详细部署说明
+- [技术文档](./PROJECT_DOCS.md) - 架构和技术文档
+- [API 测试](./TESTING.md) - API 测试指南
+
 ## API Endpoints

 ### REST API