# 一键部署快速指南

## 🚀 目标

让其他公司能够**一条命令**完成部署，无需复杂配置。

---

## 📦 部署方式

### 方式1：Docker Compose（推荐）

```bash
# 1. 克隆或下载项目
git clone <repository-url>
cd flnxi_sucai

# 2. 配置环境变量（可选，有默认值）
cp .env.example .env
# 编辑 .env 文件（可选）

# 3. 一键启动
docker compose -f docker-compose.prod.yml up -d

# 4. 等待服务启动（约30秒）
docker compose logs -f app

# 5. 访问应用
# http://your-server-ip:4320
```

### 方式2：Docker镜像（最简）

```bash
# 1. 拉取镜像（如果已发布到Docker Hub）
docker pull your-registry/flnxi-material:latest

# 2. 运行（使用外部数据库和MinIO）
docker run -d \
  --name flnxi-material \
  -p 4320:3000 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/dbname \
  -e S3_ENDPOINT=http://minio:9000 \
  -e S3_BUCKET=youyidian3d \
  your-registry/flnxi-material:latest
```

---

## ⚙️ 最小配置

### 必需的环境变量

```bash
# 数据库（必需）
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/flnxi

# S3存储（必需，使用MinIO）
S3_ENDPOINT=http://minio:9000
S3_BUCKET=youyidian3d
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin123456
S3_PUBLIC_DOMAIN=http://your-server-ip:9000/youyidian3d

# 认证（必需）
NEXTAUTH_SECRET=your-random-secret-key-here
NEXTAUTH_URL=http://your-server-ip:4320
```

### 可选的环境变量

```bash
# 站点配置（可选，有默认值）
APP_PUBLIC_URL=http://your-server-ip:4320
NEXT_PUBLIC_DEFAULT_HEADER_LOGO_URL=
NEXT_PUBLIC_DEFAULT_LOGIN_LOGO_URL=

# 功能开关（可选，默认启用）
ENABLE_REGISTRATION=true
ENABLE_USER_ACTIVATION=false
```

---

## 🔧 默认配置说明

### 数据库
- **默认数据库名**：`flnxi`
- **默认用户**：`postgres`
- **默认密码**：`youyidian123456`（**生产环境请修改**）

### MinIO
- **默认Bucket**：`youyidian3d`
- **默认访问密钥**：`minioadmin` / `minioadmin123456`（**生产环境请修改**）
- **默认端口**：9000（API），9001（控制台）

### 应用
- **默认端口**：4320
- **默认管理员**：首位注册用户自动成为超级管理员

---

## 📋 部署检查清单

### 部署前
- [ ] 检查服务器资源（建议：2核CPU，2GB内存，20GB磁盘）
- [ ] 确认Docker和Docker Compose已安装
- [ ] 确认端口4320、9000、9001未被占用
- [ ] 准备强随机字符串作为`NEXTAUTH_SECRET`

### 部署后
- [ ] 检查容器状态：`docker compose ps`
- [ ] 检查应用日志：`docker compose logs app`
- [ ] 访问健康检查：`http://your-server-ip:4320/api/health`
- [ ] 测试注册功能（首位用户自动成为管理员）
- [ ] 测试上传功能

---

## 🐛 常见问题

### 1. 容器无法启动
```bash
# 检查日志
docker compose logs app

# 常见原因：
# - 端口被占用：修改docker-compose.prod.yml中的端口映射
# - 数据库连接失败：检查DATABASE_URL配置
# - 内存不足：增加服务器内存或调整Docker资源限制
```

### 2. 无法访问应用
```bash
# 检查防火墙
sudo ufw allow 4320

# 检查容器是否运行
docker compose ps

# 检查应用日志
docker compose logs app --tail=50
```

### 3. 上传功能失败
```bash
# 检查MinIO状态
docker compose logs minio

# 检查S3配置
docker compose exec app printenv | grep S3_

# 检查上传目录权限
docker compose exec app ls -la /app/uploads
```

### 4. 数据库连接失败
```bash
# 检查PostgreSQL状态
docker compose logs postgres

# 检查数据库是否创建
docker compose exec postgres psql -U postgres -l

# 检查连接字符串
docker compose exec app printenv DATABASE_URL
```

---

## 🔒 安全建议

### 生产环境必须修改

1. **修改默认密码**
   ```bash
   # 在docker-compose.prod.yml中修改
   POSTGRES_PASSWORD=your-strong-password
   MINIO_ROOT_PASSWORD=your-strong-password
   ```

2. **设置强随机NEXTAUTH_SECRET**
   ```bash
   # 生成随机字符串
   openssl rand -base64 32
   
   # 在.env中设置
   NEXTAUTH_SECRET=生成的随机字符串
   ```

3. **配置防火墙**
   ```bash
   # 只开放必要端口
   sudo ufw allow 4320/tcp  # 应用端口
   sudo ufw allow 9000/tcp  # MinIO API（如果外部访问）
   sudo ufw allow 9001/tcp  # MinIO控制台（如果外部访问）
   ```

4. **使用HTTPS（推荐）**
   - 配置Nginx反向代理
   - 使用Let's Encrypt免费SSL证书
   - 参考：[HTTPS部署指南](./guides/HTTPS_SETUP.md)

---

## 📊 性能监控

### 资源使用监控

```bash
# 查看容器资源使用
docker stats

# 查看应用日志
docker compose logs app --tail=100 -f

# 查看数据库连接数
docker compose exec postgres psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"
```

### 健康检查

```bash
# 应用健康检查
curl http://localhost:4320/api/health

# 数据库健康检查
docker compose exec postgres pg_isready -U postgres

# MinIO健康检查
docker compose exec minio mc ready local
```

---

## 🔄 更新部署

```bash
# 1. 停止服务
docker compose down

# 2. 备份数据（重要！）
docker compose exec postgres pg_dump -U postgres flnxi > backup.sql

# 3. 拉取新镜像或重新构建
docker compose pull  # 如果使用远程镜像
# 或
docker compose build  # 如果本地构建

# 4. 启动服务
docker compose up -d

# 5. 检查状态
docker compose ps
docker compose logs app --tail=50
```

---

## 📚 相关文档

- [架构设计与编码规范](./ARCHITECTURE_AND_CODING_STANDARDS.md)
- [性能优化指南](./PERFORMANCE_OPTIMIZATION_GUIDE.md)
- [可移植部署指南](./PORTABLE_DEPLOYMENT_GUIDE.md)
- [安全部署流程](./guides/安全部署流程.md)

---

**最后更新**：2025-11-15