# Filament Admin 部署指南

## 📋 概述

本项目已优化 Docker 配置，实现：
- ✅ 国内镜像加速构建
- ✅ 最小化镜像体积（约 400MB vs 原 800MB+）
- ✅ 前端资源预编译，开箱即用
- ✅ 生产环境就绪

## 🚀 快速部署

### 方式一：使用预构建镜像（推荐）

#### 1. 在本地构建镜像
```bash
# 赋予执行权限
chmod +x build.sh deploy.sh

# 构建镜像（会自动安装依赖、编译前端、生成优化缓存）
./build.sh
```

#### 2. 传输到服务器
```bash
# 将生成的镜像文件传输到服务器
scp filamentadmin.tar.gz user@your-server:/path/to/project/

# 或使用其他传输方式
```

#### 3. 在服务器上部署
```bash
# 解压并加载镜像
gunzip -c filamentadmin.tar.gz | docker load

# 启动服务
./deploy.sh
```

### 方式二：直接构建部署

```bash
# 一键构建并部署
docker compose -f docker-compose.prod.yml build --no-cache
docker compose -f docker-compose.prod.yml up -d
```

## 📦 镜像优化详情

### 多阶段构建
1. **前端构建阶段**：使用 Node.js Alpine 构建前端资源
2. **运行时阶段**：仅保留 PHP 运行环境

### 国内镜像源
- **Alpine 源**：`mirrors.aliyun.com`
- **NPM 源**：`registry.npmmirror.com`
- **Composer 源**：`mirrors.aliyun.com/composer`

### 体积优化
- 使用 `php:8.3-cli-alpine`（~100MB）替代 `php:8.3-cli`（~500MB+）
- 合并 `RUN` 命令减少层数
- 清理 `apk`/`npm`/`composer` 缓存
- 严格 `.dockerignore` 排除不必要文件

### 预编译优化
- ✅ Laravel 配置缓存
- ✅ 路由缓存
- ✅ 视图缓存
- ✅ 前端资源编译（CSS/JS）
- ✅ Composer 自动加载优化

## 🔧 配置说明

### 环境变量

在 `.env` 文件中配置：

```env
APP_NAME="Filament Admin"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=http://your-domain.com

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=filament_admin
DB_USERNAME=root
DB_PASSWORD=

CACHE_DRIVER=file
FILESYSTEM_DISK=local
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120
```

### 端口配置

默认端口映射：`5019:8000`
可通过修改 `docker-compose.prod.yml` 调整：

```yaml
ports:
  - "8080:8000"  # 改为 8080 端口
```

## 📊 监控和维护

### 查看日志
```bash
# 实时查看日志
docker compose -f docker-compose.prod.yml logs -f

# 查看最近 100 行日志
docker compose -f docker-compose.prod.yml logs --tail=100
```

### 重启服务
```bash
# 重启
docker compose -f docker-compose.prod.yml restart

# 停止
docker compose -f docker-compose.prod.yml down

# 重新启动
docker compose -f docker-compose.prod.yml up -d
```

### 清理资源
```bash
# 删除所有资源
docker compose -f docker-compose.prod.yml down -v

# 删除镜像
docker rmi filamentadmin:latest
```

## 🐛 故障排除

### 问题 1：端口被占用
```bash
# 查看端口占用
lsof -i :5019

# 杀死占用进程
kill -9 <PID>
```

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

### 问题 3：数据库连接失败
检查 `.env` 中的数据库配置，确保数据库服务可用。

## 📈 性能优化建议

1. **生产环境建议**
   - 使用外部数据库（MySQL/PostgreSQL）
   - 配置 Redis 缓存
   - 启用 Nginx 反向代理
   - 配置 SSL 证书

2. **资源限制**
   ```yaml
   deploy:
     resources:
       limits:
         cpus: '2.0'
         memory: 1G
   ```

## 🔐 安全建议

1. 修改默认 `APP_KEY`
2. 设置强数据库密码
3. 配置防火墙规则
4. 定期更新依赖：`docker compose pull && docker compose up -d`

## 📝 更新流程

```bash
# 1. 拉取最新代码
git pull origin main

# 2. 重新构建镜像
./build.sh

# 3. 部署更新
./deploy.sh
```

## 📞 技术支持

如遇问题，请检查：
1. Docker 版本 >= 20.10
2. Docker Compose 版本 >= 2.0
3. 磁盘空间 >= 2GB
4. 内存 >= 1GB

---

**优化前**：镜像大小 800MB+，构建时间 10-15 分钟
**优化后**：镜像大小 ~400MB，构建时间 5-8 分钟（国内镜像）