# 🚀 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（推荐）
```bash
# 1. 检查配置
make check-config

# 2. 构建镜像
make build

# 3. 部署服务
make deploy

# 4. 验证部署
make verify
```

### 方法 2：使用脚本
```bash
# 1. 检查配置
./check-config.sh

# 2. 构建
./build.sh

# 3. 部署
./deploy.sh

# 4. 验证
./verify.sh
```

### 方法 3：直接 Docker Compose
```bash
# 构建并启动
docker compose -f docker-compose.prod.yml up -d --build

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

## 📊 配置详解

### .env 核心配置
```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
# 替换 .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/`

### 快速验证
```bash
./verify.sh
```

## 📈 性能优化

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

### 建议额外优化
1. **使用 Nginx 反向代理**
   ```nginx
   server {
       listen 80;
       server_name your-domain.com;
       location / {
           proxy_pass http://localhost:5019;
           proxy_set_header Host $host;
       }
   }
   ```

2. **配置 SSL 证书**
   ```bash
   # 使用 Let's Encrypt
   certbot --nginx -d your-domain.com
   ```

3. **使用 Redis 缓存**
   ```env
   CACHE_DRIVER=redis
   SESSION_DRIVER=redis
   REDIS_HOST=redis
   ```

4. **配置数据库备份**
   ```bash
   # SQLite
   cp database/database.sqlite database/backup_$(date +%Y%m%d).sqlite

   # MySQL
   mysqldump -u root -p filament_admin > backup.sql
   ```

## 🐛 常见问题

### 1. 端口占用
```bash
# 查看端口
lsof -i :5019

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

### 2. 权限错误
```bash
# 修复权限
sudo chown -R $USER:$USER storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

### 3. 数据库连接失败
```bash
# 检查配置
cat .env | grep DB_

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

### 4. 前端资源 404
```bash
# 确认构建文件存在
ls -lh public/build/assets/

# 重新构建
make build
```

## 🔐 安全建议

1. **修改默认配置**
   - 生成新 APP_KEY：`php artisan key:generate`
   - 设置强数据库密码
   - 配置防火墙规则

2. **生产环境检查**
   ```bash
   # 确保调试关闭
   grep "^APP_DEBUG" .env  # 应为 false

   # 检查日志级别
   grep "^LOG_LEVEL" .env  # 应为 info 或 warning
   ```

3. **定期更新**
   ```bash
   # 拉取最新镜像
   docker compose -f docker-compose.prod.yml pull
   docker compose -f docker-compose.prod.yml up -d
   ```

## 📞 支持

### 文档
- 📘 [部署指南](./DEPLOYMENT.md) - 完整部署说明
- 🚀 [快速开始](./QUICKSTART.md) - 一键部署指南

### 脚本帮助
```bash
make help           # 查看所有命令
./check-config.sh   # 检查配置
./verify.sh         # 验证部署
```

### 日志查看
```bash
# 实时日志
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 分钟 |
| 前端构建 | 需手动 | 自动 |
| 启动方式 | 多步操作 | 一键部署 |
| 生产就绪 | ❌ | ✅ |