math_cms

🚀 Filament Admin 生产部署方案

✅ 优化完成摘要

本项目已完成生产环境 Docker 优化，包括：

1. 📦 镜像优化

• 多阶段构建：前端构建（Node.js）+ 运行时（PHP Alpine）
• 体积减少：从 800MB+ 降至 ~400MB
• 国内镜像加速：
  • Alpine：mirrors.aliyun.com
  • NPM：registry.npmmirror.com
  • Composer：mirrors.aliyun.com/composer

2. 🎯 前端预编译

• 构建流程：Docker 构建时自动编译 CSS/JS
• 开箱即用：docker compose up -d 后无需手动构建
• 资源优化：代码分割、压缩、哈希命名

3. ⚙️ 环境配置

• 生产环境：APP_ENV=production, APP_DEBUG=false
• 日志优化：LOG_LEVEL=info
• 安全加固：禁用调试、关闭 Telescope

4. 🔧 Docker 配置

• 健康检查：自动监控容器状态
• 资源限制：CPU 2核 / 内存 1GB
• 自动重启：故障自动恢复
• 数据持久化：storage 和 database 目录挂载

📋 部署清单

必需文件

✅ Dockerfile              # 多阶段构建配置
✅ docker-compose.prod.yml # 生产环境编排
✅ .env                    # 环境变量（已配置）
✅ .env.production         # 生产配置模板
✅ build.sh               # 构建脚本
✅ deploy.sh              # 部署脚本
✅ verify.sh              # 验证脚本
✅ check-config.sh        # 配置检查脚本
✅ Makefile               # 简化操作命令
✅ DEPLOYMENT.md          # 详细部署文档
✅ QUICKSTART.md          # 快速开始指南

目录结构

FilamentAdmin/
├── Dockerfile                  # 镜像构建
├── docker-compose.prod.yml    # 生产配置
├── .env                       # 环境变量（关键配置）
├── .env.production           # 生产模板
├── build.sh                  # 构建脚本
├── deploy.sh                 # 部署脚本
├── verify.sh                 # 验证脚本
├── check-config.sh           # 配置检查
├── Makefile                  # 操作命令
├── public/build/            # 前端资源（构建后）
├── storage/                 # 存储（持久化）
└── database/                # 数据库（SQLite）

🚀 一键部署

方法 1：使用 Make（推荐）

# 1. 检查配置
make check-config

# 2. 构建镜像
make build

# 3. 部署服务
make deploy

# 4. 验证部署
make verify

方法 2：使用脚本

# 1. 检查配置
./check-config.sh

# 2. 构建
./build.sh

# 3. 部署
./deploy.sh

# 4. 验证
./verify.sh

方法 3：直接 Docker Compose

# 构建并启动
docker compose -f docker-compose.prod.yml up -d --build

# 查看状态
docker compose -f docker-compose.prod.yml ps

📊 配置详解

.env 核心配置

# 应用配置
APP_NAME="Filament Admin"
APP_ENV=production              # 生产环境
APP_DEBUG=false                 # 关闭调试
APP_URL=http://localhost:5019   # 访问地址

# 数据库（SQLite）
DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite

# API 服务（根据实际调整）
KNOWLEDGE_API_BASE=http://127.0.0.1:5011
QUESTION_BANK_API_BASE=http://127.0.0.1:6001

生产环境推荐配置（MySQL）

# 替换 .env 中的数据库配置
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=filament_admin
DB_USERNAME=filament_user
DB_PASSWORD=your_strong_password

同时取消 docker-compose.prod.yml 中 MySQL 服务的注释。

🔍 验证部署

检查项

1. ✅ 容器运行状态：docker compose -f docker-compose.prod.yml ps
2. ✅ 端口访问：curl http://localhost:5019/admin
3. ✅ 日志查看：docker compose -f docker-compose.prod.yml logs
4. ✅ 资源文件：ls -lh public/build/assets/

快速验证

./verify.sh

📈 性能优化

已实现优化

• ✅ Laravel 缓存（config, route, view）
• ✅ Composer 自动加载优化
• ✅ 前端代码压缩
• ✅ 镜像层优化
• ✅ 健康检查机制

建议额外优化

1. 使用 Nginx 反向代理

   server {
      listen 80;
      server_name your-domain.com;
      location / {
          proxy_pass http://localhost:5019;
          proxy_set_header Host $host;
      }
   }
   

2. 配置 SSL 证书

   # 使用 Let's Encrypt
   certbot --nginx -d your-domain.com
   

3. 使用 Redis 缓存

   CACHE_DRIVER=redis
   SESSION_DRIVER=redis
   REDIS_HOST=redis
   

4. 配置数据库备份

   # SQLite
   cp database/database.sqlite database/backup_$(date +%Y%m%d).sqlite
   
   # MySQL
   mysqldump -u root -p filament_admin > backup.sql
   

🐛 常见问题

1. 端口占用

# 查看端口
lsof -i :5019

# 解决方案：修改 docker-compose.prod.yml
ports:
  - "8080:8000"  # 改用其他端口

2. 权限错误

# 修复权限
sudo chown -R $USER:$USER storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

3. 数据库连接失败

# 检查配置
cat .env | grep DB_

# 验证容器内数据库
docker compose -f docker-compose.prod.yml exec filament_admin php artisan migrate:status

4. 前端资源 404

# 确认构建文件存在
ls -lh public/build/assets/

# 重新构建
make build

🔐 安全建议

1. 修改默认配置

   • 生成新 APP_KEY：php artisan key:generate
   • 设置强数据库密码
   • 配置防火墙规则

2. 生产环境检查

   # 确保调试关闭
   grep "^APP_DEBUG" .env  # 应为 false
   
   # 检查日志级别
   grep "^LOG_LEVEL" .env  # 应为 info 或 warning
   

3. 定期更新

   # 拉取最新镜像
   docker compose -f docker-compose.prod.yml pull
   docker compose -f docker-compose.prod.yml up -d
   

📞 支持

文档

• 📘 部署指南 - 完整部署说明
• 🚀 快速开始 - 一键部署指南

脚本帮助

make help           # 查看所有命令
./check-config.sh   # 检查配置
./verify.sh         # 验证部署

日志查看

# 实时日志
docker compose -f docker-compose.prod.yml logs -f

# 最近 100 行
docker compose -f docker-compose.prod.yml logs --tail=100

📈 更新日志

v1.0.0 (优化版)

• ✅ 多阶段 Docker 构建
• ✅ 国内镜像加速
• ✅ 前端资源预编译
• ✅ 生产环境优化
• ✅ 健康检查机制
• ✅ 自动化脚本
• ✅ 完整文档

---

优化效果对比：

项目	优化前	优化后
镜像大小	800MB+	~400MB
构建时间	10-15 分钟	5-8 分钟
前端构建	需手动	自动
启动方式	多步操作	一键部署
生产就绪	❌	✅