diary-family/ubuntu_pdf_deployment_guide.md

# Ubuntu服务器PDF生成功能部署和测试指南

## 概述

本文档提供在Ubuntu服务器上部署和测试家庭日报系统PDF生成功能的完整指南。

## 系统要求

- Ubuntu 20.04/22.04/24.04 LTS
- Python 3.8+
- Django 5.1.4+
- WeasyPrint 67.0+

## 1. 服务器环境准备

### 1.1 安装系统依赖

```bash
# 更新包管理器
sudo apt update

# 安装WeasyPrint系统依赖
sudo apt install -y \
    libpango-1.0-0 \
    libpangoft2-1.0-0 \
    libpangocairo-1.0-0 \
    libgdk-pixbuf-2.0-0 \
    libcairo2 \
    libgobject-2.0-0 \
    libglib-2.0-0 \
    libxml2 \
    libffi7 \
    python3-dev \
    build-essential

# 安装中文字体支持
sudo apt install -y fonts-noto-cjk fonts-wqy-microhei
```

### 1.2 验证系统依赖

```bash
# 检查关键库是否安装
ldconfig -p | grep pango
ldconfig -p | grep cairo
ldconfig -p | grep glib

# 检查字体安装
fc-list :lang=zh
```

## 2. Python环境配置

### 2.1 安装Python依赖

```bash
# 激活虚拟环境（如果有）
source venv/bin/activate

# 安装WeasyPrint
pip install weasyprint==67.0

# 验证安装
python -c "from weasyprint import HTML; print('WeasyPrint安装成功')"
```

### 2.2 验证Python环境

```bash
# 检查Python包
pip list | grep weasyprint

# 测试基本功能
python -c "
from weasyprint import HTML
html = HTML(string='<h1>测试PDF</h1><p>中文测试</p>')
html.write_pdf('test.pdf')
print('PDF生成测试成功')
"
```

## 3. 项目部署

### 3.1 上传项目文件

```bash
# 上传项目到服务器
scp -r diary-family/ user@your-server:/opt/

# 设置权限
sudo chown -R www-data:www-data /opt/diary-family
sudo chmod -R 755 /opt/diary-family
```

### 3.2 配置Django设置

确保 `diary_family/settings.py` 中的配置正确：

```python
# Reports files configuration
REPORTS_URL = '/reports/'
REPORTS_ROOT = BASE_DIR / 'reports'  # 确保此目录可写

# 确保静态文件配置正确
STATICFILES_DIRS = [BASE_DIR / 'static']
STATIC_ROOT = BASE_DIR / 'staticfiles'
```

### 3.3 创建报告目录

```bash
# 创建报告目录
mkdir -p /opt/diary-family/reports
sudo chown -R www-data:www-data /opt/diary-family/reports
sudo chmod -R 755 /opt/diary-family/reports
```

## 4. 运行PDF生成测试

### 4.1 上传测试脚本

将 `ubuntu_pdf_test.py` 上传到服务器项目根目录。

### 4.2 运行测试

```bash
cd /opt/diary-family

# 运行PDF测试
python ubuntu_pdf_test.py
```

### 4.3 测试输出说明

测试脚本会检查以下内容：
- ✅ Ubuntu环境验证
- ✅ 系统依赖库检查
- ✅ Python依赖检查
- ✅ 字体支持测试
- ✅ PDF生成功能测试
- ✅ Celery PDF任务测试

## 5. 生产环境配置

### 5.1 Gunicorn配置

确保 `gunicorn_config.py` 包含正确的设置：

```python
# gunicorn_config.py
bind = "0.0.0.0:8000"
workers = 4
worker_class = "sync"
max_requests = 1000
max_requests_jitter = 100
```

### 5.2 Nginx配置

```nginx
# /etc/nginx/sites-available/diary-family
server {
    listen 80;
    server_name your-domain.com;
    
    location /reports/ {
        alias /opt/diary-family/reports/;
        expires 1h;
        add_header Cache-Control "public";
    }
    
    location /static/ {
        alias /opt/diary-family/staticfiles/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    location / {
        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;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### 5.3 Celery配置

```bash
# 启动Celery worker
celery -A diary_family worker --loglevel=info

# 启动Celery beat（定时任务）
celery -A diary_family beat --loglevel=info
```

## 6. 故障排除

### 6.1 常见问题

#### 问题1: WeasyPrint导入错误
```
ImportError: cannot load library 'libgobject-2.0-0'
```
**解决方案**:
```bash
sudo apt install libgobject-2.0-0 libglib-2.0-0
```

#### 问题2: 中文字体显示异常
**解决方案**:
```bash
sudo apt install fonts-noto-cjk fonts-wqy-microhei
fc-cache -fv  # 刷新字体缓存
```

#### 问题3: PDF生成权限错误
**解决方案**:
```bash
sudo chown -R www-data:www-data /opt/diary-family/reports
sudo chmod -R 755 /opt/diary-family/reports
```

### 6.2 日志检查

```bash
# 检查应用日志
tail -f /var/log/gunicorn/diary-family.log

# 检查Celery日志
tail -f /var/log/celery/worker.log

# 检查Nginx日志
tail -f /var/log/nginx/error.log
```

## 7. 自动化测试

### 7.1 创建测试脚本

创建 `deploy_test.sh` 自动化测试脚本：

```bash
#!/bin/bash
# deploy_test.sh

echo "=== 开始PDF生成功能部署测试 ==="

# 检查系统依赖
echo "1. 检查系统依赖..."
for lib in libpango-1.0-0 libcairo2 libglib-2.0-0; do
    if ldconfig -p | grep -q $lib; then
        echo "✓ $lib 已安装"
    else
        echo "✗ $lib 未安装"
    fi
done

# 检查Python依赖
echo "2. 检查Python依赖..."
if python -c "import weasyprint" &>/dev/null; then
    echo "✓ WeasyPrint 已安装"
else
    echo "✗ WeasyPrint 未安装"
fi

# 运行Python测试
echo "3. 运行PDF功能测试..."
cd /opt/diary-family
python ubuntu_pdf_test.py

echo "=== 测试完成 ==="
```

### 7.2 设置定时健康检查

```bash
# 添加到crontab
# 每天检查PDF生成功能
0 2 * * * /opt/diary-family/deploy_test.sh >> /var/log/pdf_health_check.log 2>&1
```

## 8. 监控和维护

### 8.1 监控指标

- PDF文件生成成功率
- 文件大小和生成时间
- 系统资源使用情况
- 错误日志频率

### 8.2 定期维护

```bash
# 清理旧PDF文件（保留最近30天）
find /opt/diary-family/reports -name "*.pdf" -mtime +30 -delete

# 检查磁盘空间
df -h /opt/diary-family/reports

# 重启服务（如果需要）
sudo systemctl restart gunicorn
sudo systemctl restart celery
```

## 总结

通过以上步骤，您可以在Ubuntu服务器上成功部署和测试PDF生成功能。关键点包括：

1. **系统依赖**: 确保所有GTK+相关库正确安装
2. **字体支持**: 安装中文字体以确保中文内容正确显示
3. **权限配置**: 确保报告目录有正确的写入权限
4. **监控维护**: 设置定期检查和清理机制

测试脚本 `ubuntu_pdf_test.py` 提供了全面的功能验证，确保PDF生成在生产环境中稳定运行。