flnxi-Wu/docs/archive/一键部署快速指南.md

一键部署快速指南

🚀 目标

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

---

📦 部署方式

方式1：Docker Compose（推荐）

# 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镜像（最简）

# 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

---

⚙️ 最小配置

必需的环境变量

# 数据库（必需）
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

可选的环境变量

# 站点配置（可选，有默认值）
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. 容器无法启动

# 检查日志
docker compose logs app

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

2. 无法访问应用

# 检查防火墙
sudo ufw allow 4320

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

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

3. 上传功能失败

# 检查MinIO状态
docker compose logs minio

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

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

4. 数据库连接失败

# 检查PostgreSQL状态
docker compose logs postgres

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

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

---

🔒 安全建议

生产环境必须修改

1. 修改默认密码

   # 在docker-compose.prod.yml中修改
   POSTGRES_PASSWORD=your-strong-password
   MINIO_ROOT_PASSWORD=your-strong-password
   

2. 设置强随机NEXTAUTH_SECRET

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

3. 配置防火墙

   # 只开放必要端口
   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部署指南

---

📊 性能监控

资源使用监控

# 查看容器资源使用
docker stats

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

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

健康检查

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

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

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

---

🔄 更新部署

# 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

---

📚 相关文档

• 架构设计与编码规范
• 性能优化指南
• 可移植部署指南
• 安全部署流程

---

最后更新：2025-11-15