部署指南

本文档提供了 Unicode Framework 在生产环境的部署指南。

部署前准备

系统要求

• PHP >= 8.1
• Composer
• Web 服务器（Nginx/Apache）
• 数据库（MySQL/PostgreSQL/SQLite）
• Redis（可选，用于缓存和队列）

检查清单

• [ ] PHP 版本 >= 8.1
• [ ] 必需的 PHP 扩展已安装
• [ ] Composer 已安装
• [ ] 数据库已创建
• [ ] 环境变量已配置
• [ ] 文件权限已设置

服务器配置

Nginx 配置

server {
    listen 80;
    server_name example.com;
    root /path/to/project/public;
    index index.php;
location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
location ~ /\. {
        deny all;
    }
}

Apache 配置

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /path/to/project/public
<Directory /path/to/project/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

PHP-FPM 配置

; php-fpm.conf
pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20

应用部署

1. 克隆代码

git clone https://github.com/your-repo/framework.git
cd framework

2. 安装依赖

<h1 id="安装-composer-依赖">安装 Composer 依赖</h1>
composer install --no-dev --optimize-autoloader
<h1 id="安装-nodejs-依赖如果使用-vue3">安装 Node.js 依赖（如果使用 Vue3）</h1>
npm install --production

3. 配置环境

<h1 id="复制环境配置文件">复制环境配置文件</h1>
cp .env.example .env
<h1 id="编辑环境变量">编辑环境变量</h1>
nano .env

4. 生成密钥

<h1 id="如果需要应用密钥">如果需要应用密钥</h1>
php console key:generate

5. 运行迁移

<h1 id="运行数据库迁移">运行数据库迁移</h1>
php console migrate
<h1 id="运行种子数据可选">运行种子数据（可选）</h1>
php console db:seed

6. 优化应用

<h1 id="生成路由缓存">生成路由缓存</h1>
php console route:cache
<h1 id="生成配置缓存如果支持">生成配置缓存（如果支持）</h1>
<h1 id="注意配置缓存由-config-类在生产环境自动处理不需要-configcache-命令">注意：配置缓存由 Config 类在生产环境自动处理，不需要 config:cache 命令</h1>
<h1 id="php-console-routecache-只需要缓存路由">php console route:cache  # 只需要缓存路由</h1>
<h1 id="编译视图如果支持">编译视图（如果支持）</h1>
php console view:compile

7. 设置权限

<h1 id="设置存储目录权限">设置存储目录权限</h1>
chmod -R 775 storage
chmod -R 775 bootstrap/cache
<h1 id="设置文件所有者">设置文件所有者</h1>
chown -R www-data:www-data storage
chown -R www-data:www-data bootstrap/cache

环境配置

.env 文件

<h1 id="应用环境">应用环境</h1>
APP_ENV=production
APP_DEBUG=false
<h1 id="数据库配置">数据库配置</h1>
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password
<h1 id="缓存配置">缓存配置</h1>
CACHE_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
<h1 id="队列配置">队列配置</h1>
QUEUE_CONNECTION=database
<h1 id="jwt-配置">JWT 配置</h1>
JWT_SECRET=your-secret-key

安全配置

<h1 id="推荐使用强密钥">✅ 推荐：使用强密钥</h1>
JWT_SECRET=your-very-long-and-random-secret-key
<h1 id="推荐禁用调试">✅ 推荐：禁用调试</h1>
APP_DEBUG=false
<h1 id="推荐使用-https">✅ 推荐：使用 HTTPS</h1>
APP_URL=https://example.com

性能优化

OPcache 配置

; php.ini
opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0

路由缓存

<h1 id="生成路由缓存">生成路由缓存</h1>
php console route:cache
<h1 id="清除路由缓存">清除路由缓存</h1>
php console route:clear

视图缓存

// config/view.php
return [
    'engines' => [
        'smarty' => [
            'caching' => true,
            'cache_lifetime' => 3600,
        ],
    ],
];

队列 Worker

使用 Supervisor

<h1 id="etcsupervisorconfdqueue-workerconf">/etc/supervisor/conf.d/queue-worker.conf</h1>
[program:queue-worker]
command=php /path/to/project/console queue:work --sleep=3 --tries=3
directory=/path/to/project
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/path/to/project/storage/logs/queue-worker.log

启动 Supervisor

<h1 id="重新加载配置">重新加载配置</h1>
sudo supervisorctl reread
sudo supervisorctl update
<h1 id="启动-worker">启动 Worker</h1>
sudo supervisorctl start queue-worker:*
<h1 id="查看状态">查看状态</h1>
sudo supervisorctl status

任务调度

Cron 配置

<h1 id="编辑-crontab">编辑 crontab</h1>
crontab -e
<h1 id="添加以下行每分钟执行一次">添加以下行（每分钟执行一次）</h1>
    * cd /path/to/project && php console schedule:run >> /dev/null 2>&1

监控和维护

日志监控

<h1 id="查看应用日志">查看应用日志</h1>
tail -f storage/logs/app.log
<h1 id="查看错误日志">查看错误日志</h1>
tail -f storage/logs/error.log
<h1 id="查看队列日志">查看队列日志</h1>
tail -f storage/logs/queue-worker.log

性能监控

<h1 id="使用系统监控工具">使用系统监控工具</h1>
htop
iotop
netstat -tulpn

备份

<h1 id="备份数据库">备份数据库</h1>
mysqldump -u username -p database_name > backup.sql
<h1 id="备份文件">备份文件</h1>
tar -czf backup-$(date +%Y%m%d).tar.gz storage/ bootstrap/cache/

更新部署

<h1 id="1-拉取最新代码">1. 拉取最新代码</h1>
git pull origin main
<h1 id="2-安装依赖">2. 安装依赖</h1>
composer install --no-dev --optimize-autoloader
<h1 id="3-运行迁移">3. 运行迁移</h1>
php console migrate
<h1 id="4-清除缓存">4. 清除缓存</h1>
php console route:clear
<h1 id="注意配置缓存由-config-类自动处理不需要-configclear-命令">注意：配置缓存由 Config 类自动处理，不需要 config:clear 命令</h1>
<h1 id="php-console-routeclear-只需要清除路由缓存">php console route:clear  # 只需要清除路由缓存</h1>
<h1 id="5-重新生成缓存">5. 重新生成缓存</h1>
php console route:cache
<h1 id="6-重启服务">6. 重启服务</h1>
sudo supervisorctl restart queue-worker:*
sudo systemctl restart php8.1-fpm

安全配置

文件权限

<h1 id="设置正确的文件权限">设置正确的文件权限</h1>
find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;
<h1 id="存储和缓存目录">存储和缓存目录</h1>
chmod -R 775 storage bootstrap/cache

HTTPS 配置

<h1 id="nginx-https-配置">Nginx HTTPS 配置</h1>
server {
    listen 443 ssl http2;
    server_name example.com;
ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
# SSL 配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
}

防火墙

<h1 id="配置防火墙">配置防火墙</h1>
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

常见问题

Q: 部署后出现 500 错误？

A: 检查：

• 文件权限是否正确
• .env 文件是否配置正确
• 日志文件查看错误信息
• PHP 错误日志

Q: 如何查看部署日志？

A: 查看 storage/logs/ 目录下的日志文件。

Q: 如何回滚部署？

A: 使用 Git 回滚到上一个版本，然后重新部署。

Q: 队列 Worker 不工作？

A: 检查 Supervisor 配置和状态，查看队列日志。

Q: 如何优化部署速度？

A: 使用 CI/CD 自动化部署，使用部署脚本。

相关文档

• 性能优化 - 性能优化建议
• 故障排查 - 常见问题解决
• 安全指南 - 安全配置