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 安装系统依赖

# 更新包管理器
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 update && sudo apt install libcairo2-dev pkg-config


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

1.2 验证系统依赖

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

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

2. Python环境配置

2.1 安装Python依赖

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

# 安装WeasyPrint
pip install weasyprint==67.0

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

2.2 验证Python环境

# 检查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 上传项目文件

# 上传项目到服务器
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 中的配置正确：

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

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

3.3 创建报告目录

# 创建报告目录
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 运行测试

cd /opt/diary-family

# 运行PDF测试
python ubuntu_pdf_test.py

4.3 测试输出说明

测试脚本会检查以下内容：

• ✅ Ubuntu环境验证
• ✅ 系统依赖库检查
• ✅ Python依赖检查
• ✅ 字体支持测试
• ✅ PDF生成功能测试
• ✅ Celery PDF任务测试

5. 生产环境配置

5.1 Gunicorn配置

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

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

5.2 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配置

# 启动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'

解决方案:

sudo apt install libgobject-2.0-0 libglib-2.0-0

问题2: 中文字体显示异常

解决方案:

sudo apt install fonts-noto-cjk fonts-wqy-microhei
fc-cache -fv  # 刷新字体缓存

问题3: PDF生成权限错误

解决方案:

sudo chown -R www-data:www-data /opt/diary-family/reports
sudo chmod -R 755 /opt/diary-family/reports

6.2 日志检查

# 检查应用日志
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 自动化测试脚本：

#!/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 设置定时健康检查

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

8. 监控和维护

8.1 监控指标

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

8.2 定期维护

# 清理旧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生成在生产环境中稳定运行。