flnxi-Wu/docs/guides/CUSTOMER_README.md

FLNXI素材库 - 安装使用手册

专业的3D素材管理与分享平台

📋 系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+/CentOS 7+)
• Docker: 20.10 或更高版本
• Docker Compose: 2.0 或更高版本
• 内存: 最低 2GB，推荐 4GB+
• 磁盘: 最低 10GB 可用空间
• 网络: 可访问互联网（下载镜像）

🚀 快速安装

第一步：检查 Docker 环境

如果未安装 Docker，请先安装：

Ubuntu/Debian:

curl -fsSL https://get.docker.com | sh
sudo systemctl start docker
sudo systemctl enable docker

CentOS:

curl -fsSL https://get.docker.com | sh
sudo systemctl start docker
sudo systemctl enable docker

验证安装：

docker --version
docker compose version

第二步：解压安装包

# 解压文件
tar -xzf flnxi-material-vX.X.X.tar.gz
cd flnxi-material-vX.X.X

# 添加执行权限
chmod +x *.sh

第三步：配置服务器信息

编辑 .env 文件：

vim .env
# 或
nano .env

必须修改的配置：

# 修改为您的服务器IP地址
SERVER_IP=192.168.1.100

可选修改（建议）：

# 修改端口（如果有冲突）
APP_PORT=4320
MINIO_API_PORT=9000
MINIO_CONSOLE_PORT=9001

# 修改密码（建议使用强密码）
POSTGRES_PASSWORD=your-strong-password
MINIO_ROOT_PASSWORD=your-strong-password
NEXTAUTH_SECRET=your-random-secret-key

第四步：运行安装

./install.sh

安装过程约需 5-10 分钟，脚本会自动：

• ✅ 检测环境
• ✅ 配置服务
• ✅ 下载镜像
• ✅ 启动服务
• ✅ 初始化数据库
• ✅ 配置存储

第五步：访问系统

安装完成后，通过浏览器访问：

应用首页:

http://YOUR_SERVER_IP:4320

MinIO 管理控制台:

http://YOUR_SERVER_IP:9001
账号: minioadmin
密码: (查看 .env 文件中的 MINIO_ROOT_PASSWORD)

👤 首次使用

1. 注册账号

访问应用首页，点击「注册」按钮创建账号。

2. 设置管理员权限

注册后，需要将账号提升为管理员：

方法一：使用 Prisma Studio（推荐）

docker compose exec app npx prisma studio

然后在浏览器中打开 http://localhost:5555，找到您的用户，将 role 字段改为 ADMIN。

方法二：使用数据库命令

docker compose exec postgres psql -U postgres -d flnxi -c \
  "UPDATE users SET role='ADMIN' WHERE email='your@email.com';"

将 your@email.com 替换为您的注册邮箱。

3. 开始使用

现在您可以：

• ✅ 上传 3D 素材
• ✅ 管理用户
• ✅ 配置系统设置
• ✅ 查看统计数据

🔧 常用操作

启动服务

# 快速启动
./quick-start.sh

# 或使用 docker compose
docker compose up -d

停止服务

docker compose down

重启服务

docker compose restart

# 重启特定服务
docker compose restart app

查看日志

# 查看所有日志
docker compose logs -f

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

# 查看最近100行日志
docker compose logs --tail=100

查看服务状态

docker compose ps

进入容器

# 进入应用容器
docker compose exec app sh

# 进入数据库容器
docker compose exec postgres psql -U postgres -d flnxi

💾 数据备份

备份数据库

# 导出数据库
docker compose exec postgres pg_dump -U postgres flnxi > backup_$(date +%Y%m%d).sql

# 恢复数据库
docker compose exec -T postgres psql -U postgres flnxi < backup_20240101.sql

备份上传文件

# 备份 uploads 目录
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz uploads/

# 恢复文件
tar -xzf uploads_backup_20240101.tar.gz

备份 MinIO 数据

# 导出 MinIO 数据
docker compose exec minio tar -czf /tmp/minio_backup.tar.gz /data
docker compose cp minio:/tmp/minio_backup.tar.gz ./minio_backup_$(date +%Y%m%d).tar.gz

定时备份（推荐）

创建自动备份脚本：

cat > backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# 备份数据库
docker compose exec -T postgres pg_dump -U postgres flnxi > $BACKUP_DIR/db_$DATE.sql

# 备份文件
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz uploads/

# 删除7天前的备份
find $BACKUP_DIR -name "*.sql" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete
EOF

chmod +x backup.sh

# 添加到 crontab（每天凌晨2点备份）
crontab -e
# 添加: 0 2 * * * /path/to/backup.sh

🔄 系统更新

更新到新版本

# 1. 备份数据（重要！）
./backup.sh

# 2. 停止服务
docker compose down

# 3. 更新镜像（如有新版本的 docker-compose.yml，请替换）
docker compose pull

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

# 5. 查看日志确认启动成功
docker compose logs -f

🔥 防火墙配置

如果无法访问服务，请检查防火墙设置：

Ubuntu (ufw):

sudo ufw allow 4320/tcp
sudo ufw allow 9000/tcp
sudo ufw allow 9001/tcp
sudo ufw reload

CentOS (firewalld):

sudo firewall-cmd --permanent --add-port=4320/tcp
sudo firewall-cmd --permanent --add-port=9000/tcp
sudo firewall-cmd --permanent --add-port=9001/tcp
sudo firewall-cmd --reload

⚠️ 故障排查

问题1: 无法访问应用

检查服务状态:

docker compose ps

查看日志:

docker compose logs app

检查端口:

netstat -tlnp | grep 4320

问题2: 数据库连接失败

检查数据库状态:

docker compose ps postgres
docker compose logs postgres

重启数据库:

docker compose restart postgres

问题3: 图片无法显示

检查 MinIO 状态:

docker compose ps minio
docker compose logs minio

验证 MinIO 配置:

docker compose exec minio mc alias set local http://localhost:9000 minioadmin YOUR_PASSWORD
docker compose exec minio mc ls local/

检查 .env 配置:

# 确认 SERVER_IP 配置正确
cat .env | grep SERVER_IP

问题4: 磁盘空间不足

查看磁盘使用:

df -h
docker system df

清理 Docker 缓存:

docker system prune -a

查看日志文件大小:

docker compose logs --tail=0 | wc -l

问题5: 服务无响应

重启所有服务:

docker compose restart

完全重建:

docker compose down
docker compose up -d

📊 性能优化

调整 Docker 资源

编辑 docker-compose.yml：

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

启用日志轮转

编辑 docker-compose.yml：

services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

配置 Nginx 反向代理（推荐）

可以使用 Nginx 提供：

• SSL/HTTPS 支持
• 静态文件缓存
• 负载均衡
• 更好的性能

配置示例（nginx.conf）:

server {
    listen 80;
    server_name yourdomain.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:4320;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /minio/ {
        proxy_pass http://localhost:9000/;
        proxy_set_header Host $host;
    }
}

🔒 安全建议

1. 修改默认密码: 务必在 .env 中修改所有默认密码
2. 启用 HTTPS: 使用 Nginx + Let's Encrypt 配置 SSL
3. 限制访问: 配置防火墙只开放必要端口
4. 定期备份: 设置自动备份，并保存到异地
5. 及时更新: 定期检查并更新到最新版本
6. 监控日志: 定期查看日志，发现异常及时处理

📞 技术支持

遇到问题时，请提供以下信息：

# 1. 系统信息
uname -a
docker --version
docker compose version

# 2. 服务状态
docker compose ps

# 3. 日志信息
docker compose logs --tail=100

# 4. 配置信息（注意隐藏密码）
cat .env | grep -v PASSWORD | grep -v SECRET

📝 常见问题 FAQ

Q: 可以在 Windows 上安装吗？ A: 可以，但推荐使用 Linux。Windows 需要先安装 Docker Desktop。

Q: 如何修改端口？ A: 编辑 .env 文件中的 APP_PORT，然后执行 docker compose up -d。

Q: 数据存储在哪里？ A:

• 数据库: Docker volume postgres_data
• MinIO 文件: Docker volume minio_data
• 上传文件: ./uploads 目录

Q: 如何迁移到新服务器？ A:

1. 备份所有数据
2. 在新服务器安装系统
3. 恢复数据
4. 修改 .env 中的 SERVER_IP

Q: 忘记管理员密码怎么办？ A: 可以直接在数据库中重置密码，或创建新管理员账号。

Q: 支持多少用户同时在线？ A: 根据服务器配置，推荐配置：2GB内存支持 50-100 用户。

📄 许可证

本软件为商业授权软件，使用受许可协议约束。

---

感谢使用FLNXI素材库管理系统！

如有疑问，请联系技术支持。