gongxiangp2/yedir

图片背景处理工具文档

项目概述

这是一个基于Node.js的图片背景处理Web应用，提供背景移除、背景生成、图像修复、海报生成等多种图像处理功能。应用采用前后端分离架构，后端提供RESTful API，前端通过静态HTML页面与后端交互。

系统架构

图片背景处理工具
├── 前端层
│   ├── 用户界面 (HTML/CSS/JS)
│   ├── 管理员界面
│   └── 用户认证页面
├── 后端服务
│   ├── API服务 (Express)
│   ├── 认证服务 (JWT)
│   └── 图像处理服务
├── 数据存储
│   ├── 数据库 (MongoDB)
│   └── 对象存储 (AWS S3)
└── 外部服务集成
    ├── 背景移除 API (remove.bg)
    ├── 背景生成 API (阿里云)
    ├── 图像合成 API
    ├── 海报生成 API
    └── 3D模型生成 API (Tripo3D)

目录结构

xiaogongju/
├── config/              # 配置文件
│   ├── nginx.conf       # Nginx配置
│   └── ecosystem.config.js # PM2配置
├── node_modules/        # 依赖包
├── public/              # 静态资源
│   ├── admin/           # 管理员页面
│   ├── css/             # 样式文件
│   ├── js/              # 客户端脚本
│   ├── user/            # 用户页面
│   ├── index.html       # 主页
│   ├── login.html       # 登录页
│   ├── register.html    # 注册页
│   ├── profile.html     # 用户资料页
│   └── ...
├── scripts/             # 脚本文件
│   ├── deploy.sh        # 部署脚本
│   └── start.sh         # 启动脚本
├── server/              # 服务器端代码
│   ├── db/              # 数据库连接
│   ├── middleware/      # 中间件
│   ├── models/          # 数据模型
│   ├── routes/          # 路由
│   ├── utils/           # 工具函数
│   └── server.js        # 主服务器文件
├── .env                 # 环境变量
├── .env.example         # 环境变量示例
├── .gitignore           # Git忽略文件
├── init-db.js           # 数据库初始化脚本
├── package.json         # 项目配置
├── package-lock.json    # 依赖锁定文件
├── S3_MIGRATION_GUIDE.md # S3迁移指南
├── setup-mongodb.sh     # MongoDB设置脚本
└── test-db-connection.js # 数据库连接测试

技术栈

后端

• 运行环境: Node.js
• Web框架: Express
• 数据库: MongoDB + Mongoose
• 认证: JWT (JSON Web Tokens)
• 存储: AWS S3对象存储
• 部署: PM2, Nginx

前端

• HTML/CSS/JavaScript
• Bootstrap (基于页面结构推测)

外部API集成

• 背景移除: remove.bg API
• 背景生成/图像合成/海报生成: 阿里云智能API
• 3D模型生成: Tripo3D API

前端功能

应用"由壹点AIGC"提供以下主要功能模块：

1. 页面总体结构

• 顶部导航栏：品牌标识、版本信息和用户链接
• 左侧侧边栏：功能导航菜单
• 主内容区域：当前功能的操作界面

2. 用户认证流程

• 完整的登录/注册/登出功能
• 基于JWT令牌和localStorage的认证机制
• 用户角色区分（管理员/普通用户）

3. 主要功能模块

• 去除背景：自动移除图片背景
• 生成背景：为透明背景图片智能生成新背景
• 局部重绘：智能修复和重绘图像区域
• 图像拓展：智能扩展图像边界
• 线稿生图：将线稿转换为彩色图像
• 创意海报：一键生成精美海报
• 视觉分析：图像内容识别和提取
• 虚拟模特：生成穿戴商品的虚拟模特
• 图生3D模型：从2D图像生成3D模型

4. 前端架构

• 模块化设计：独立JavaScript文件实现各功能
• 命名空间管理：通过appExtensions组织模块
• 动态内容加载：功能区域根据选择动态更新
• 事件委托：菜单交互和功能激活

详细的用户界面文档可参考 UI指南。

环境配置

应用使用.env文件进行环境配置，主要包括以下配置项：

# 服务器配置
PORT=3000
NODE_ENV=development

# 用户认证相关配置
JWT_SECRET=your_jwt_secret_key_here

# 数据库配置
MONGODB_URI=mongodb://localhost:27017/xiaogongju

# AWS S3存储配置
MINIO_ENDPOINT=s3.ap-southeast-1.amazonaws.com
MINIO_PORT=443
MINIO_USE_SSL=true
MINIO_ACCESS_KEY=your_aws_access_key
MINIO_SECRET_KEY=your_aws_secret_key
MINIO_BUCKET_NAME=your_bucket_name
MINIO_REGION=ap-southeast-1
USE_S3_STORAGE=true

# API配置
REMOVE_BG_API_KEY=your_api_key
GENERATE_BG_API_KEY=your_api_key
REPAINT_API_KEY=your_api_key
...

数据模型

用户模型 (User)

{
  username: String,
  email: String,
  password: String, // 加密存储
  role: String,     // 'admin' 或 'user'
  credits: Number   // 用户积分
}

系统默认创建一个管理员账户：

• 用户名: admin
• 邮箱: admin@example.com
• 密码: Admin123!
• 角色: admin
• 积分: 100

API 端点

主要API端点包括：

认证

• POST /api/auth/register - 用户注册
• POST /api/auth/login - 用户登录
• POST /api/auth/logout - 用户登出
• POST /api/auth/forgot-password - 忘记密码

用户管理

• GET /api/users/profile - 获取用户资料
• PUT /api/users/profile - 更新用户资料
• PUT /api/users/password - 修改密码

图像处理

• POST /api/images/remove-bg - 移除图片背景
• POST /api/images/generate-bg - 生成图片背景
• POST /api/images/repaint - 图像重绘
• POST /api/images/poster - 生成海报
• POST /api/images/upload - 上传图片

积分管理

• GET /api/credits - 获取用户积分
• POST /api/credits/purchase - 购买积分

设置开发环境

前提条件

• Node.js (v12+)
• MongoDB
• AWS S3存储桶及访问凭证

安装步骤

1. 克隆仓库

   git clone [仓库URL]
   cd xiaogongju
   

2. 安装依赖

   npm install
   

3. 配置环境变量

   cp .env.example .env
   # 编辑.env文件，填入必要的配置
   

4. 设置MongoDB

   bash setup-mongodb.sh
   

5. 初始化数据库

   node init-db.js
   

6. 启动开发服务器

   npm run dev
   

7. 访问应用

   http://localhost:3000
   

Docker部署

本项目支持使用Docker进行部署，提供了完整的容器化配置。

前提条件

• Docker
• Docker Compose
• MongoDB Atlas账户（或其他云MongoDB服务）
• AWS S3存储桶及访问凭证

目录结构

xiaogongju/
├── ...
├── Dockerfile              # Docker镜像构建文件
├── docker-compose.yml      # Docker Compose配置
├── docker-manager.sh       # Docker部署管理脚本
└── ...

环境配置

使用Docker部署前，需要确保.env文件中配置了正确的环境变量：

# 服务器配置
PORT=3225
NODE_ENV=production
HOST=0.0.0.0

# MongoDB Atlas配置
MONGODB_URI=your_mongodb_atlas_connection_string

# S3存储配置
MINIO_ENDPOINT=s3.ap-southeast-1.amazonaws.com
MINIO_PORT=443
MINIO_USE_SSL=true
MINIO_ACCESS_KEY=your_aws_access_key
MINIO_SECRET_KEY=your_aws_secret_key
MINIO_BUCKET_NAME=your_bucket_name
MINIO_REGION=ap-southeast-1
USE_S3_STORAGE=true

# 其他API配置
...

部署步骤

1. 克隆代码仓库

git clone https://github.com/your-repo/xiaogongju.git
cd xiaogongju

2. 配置环境变量

cp .env.example .env
# 编辑.env文件，填入你的MongoDB Atlas连接字符串和S3配置

3. 使用Docker部署管理脚本

# 给脚本添加执行权限
chmod +x docker-manager.sh

# 构建并启动服务
./docker-manager.sh rebuild

# 查看容器状态
./docker-manager.sh ps

# 查看应用日志
./docker-manager.sh logs

4. 访问应用

应用将在http://localhost:3225上运行（除非在.env中修改了端口）。

Docker部署管理脚本

docker-manager.sh脚本提供以下命令:

./docker-manager.sh start     # 启动所有服务
./docker-manager.sh stop      # 停止所有服务
./docker-manager.sh restart   # 重启所有服务
./docker-manager.sh build     # 构建应用镜像
./docker-manager.sh rebuild   # 重新构建并启动应用
./docker-manager.sh logs      # 查看应用日志
./docker-manager.sh ps        # 显示容器状态
./docker-manager.sh clean     # 清理未使用的镜像和体积
./docker-manager.sh backup    # 备份S3数据
./docker-manager.sh help      # 显示帮助信息

服务组件

Docker环境包含以下服务:

1. app: Node.js应用服务

   • 基于优化的多阶段构建的Node.js容器
   • 运行Express应用服务器
   • 连接到MongoDB Atlas云数据库
   • 使用AWS S3存储图片和处理结果

2. redis (可选): Redis缓存服务

   • 用于提高应用性能
   • 缓存频繁访问的数据

数据持久化

Docker部署使用命名卷来持久化Redis数据:

• redis-data: Redis缓存数据

图片和文件存储在AWS S3中，确保数据的持久性和高可用性。

从MinIO迁移到S3

如果您从本地MinIO迁移到AWS S3，请参考 S3迁移指南 获取详细步骤。

外部API集成

背景移除 (remove.bg)

• API密钥配置在REMOVE_BG_API_KEY环境变量中
• API端点: REMOVE_BG_API_URL=https://api.remove.bg/v1.0/removebg

背景生成/图像合成 (阿里云)

• API密钥配置在GENERATE_BG_API_KEY和REPAINT_API_KEY环境变量中
• 支持多种图像处理模型和场景

3D模型生成 (Tripo3D)

• API密钥配置在TRIPO3D_API_KEY环境变量中
• 支持文本到模型、图像到模型、多视图到模型等功能

用户指南

注册和登录

1. 访问首页，点击"注册"
2. 填写用户名、邮箱和密码
3. 注册成功后，使用凭证登录

图像处理

1. 登录后，上传需要处理的图片
2. 选择需要的处理功能（如背景移除、背景生成等）
3. 设置相关参数
4. 处理完成后，可以下载或保存结果

充值积分

1. 在个人资料页面，查看当前积分
2. 点击"充值积分"，选择充值方式和金额
3. 完成支付后，积分将自动添加到账户

维护与排错

日志

• 应用日志位于logs/目录
• 使用PM2时，可通过pm2 logs查看实时日志

常见问题

• 数据库连接失败: 检查MongoDB连接URI是否正确
• 图像处理API错误: 验证API密钥是否有效，配额是否足够
• S3存储错误: 确认AWS S3配置是否正确，访问凭证是否有效

故障排除

如果遇到问题，请尝试以下步骤：

1. 检查日志

   # 本地开发环境
   cat app.log
   
   # Docker环境
   ./manage-docker.sh logs
   

2. 确保所有环境变量已正确设置

3. 检查MongoDB连接

   node test-db-connection.js
   

4. 解决.env文件权限问题（Docker环境）

   如果在日志中看到类似 Error: EACCES: permission denied, open '/app/.env' 的错误，可通过以下方法解决：

   # 方法1: 修改容器内.env文件权限
   docker exec -it xiaogongju chmod 666 /app/.env
   
   # 方法2: 确保正确挂载.env文件(在docker-compose.yml中)
   # 添加以下配置到volumes部分:
   # - ./.env:/app/.env
   

联系与支持

如有任何问题或建议，请联系项目维护团队：

• 邮箱: support@example.com
• 项目仓库: [GitHub仓库链接]

小工具应用

一个功能丰富的Node.js应用程序，提供各种图像处理和AI生成功能。

功能特点

• 图像背景生成
• 图像背景移除
• 图像重绘
• 海报生成
• 视频生成
• 多模态生成
• MongoDB数据存储
• AWS S3对象存储

技术栈

• Node.js
• Express.js
• MongoDB
• AWS S3
• Docker

部署方式

本地开发环境

1. 克隆仓库

   git clone <repository-url>
   cd xiaogongju
   

2. 安装依赖

   npm install
   

3. 配置环境变量

   cp .env.example .env
   # 编辑.env文件，填入必要的配置
   

4. 启动应用

   npm run start
   

Docker部署

我们提供了Docker部署方式，方便在各种环境中快速部署应用。

1. 使用管理脚本部署

   # 赋予脚本执行权限
   chmod +x manage-docker.sh
   
   # 构建并启动容器
   ./manage-docker.sh rebuild
   # 上传文件夹权限
   chmod -R 777 server/uploads public/uploads uploads
   

2. 管理容器

   ./manage-docker.sh start    # 启动容器
   ./manage-docker.sh stop     # 停止容器
   ./manage-docker.sh restart  # 重启容器
   ./manage-docker.sh logs     # 查看日志
   ./manage-docker.sh status   # 查看状态
   ./manage-docker.sh shell    # 进入容器shell
   ./manage-docker.sh update   # 更新应用
   

详细的Docker部署和更新指南请参考 Docker部署指南。

环境变量配置

应用需要以下环境变量才能正常工作：

• PORT: 应用监听端口 (默认: 3225)
• NODE_ENV: 环境 (development/production)
• MONGODB_URI: MongoDB连接字符串
• MINIO_ENDPOINT: S3服务器地址 (如s3.ap-southeast-1.amazonaws.com)
• MINIO_PORT: S3服务器端口 (如443)
• MINIO_ACCESS_KEY: S3访问密钥
• MINIO_SECRET_KEY: S3秘密密钥
• MINIO_BUCKET_NAME: S3存储桶名称
• MINIO_REGION: S3区域
• MINIO_USE_SSL: 是否使用SSL连接S3 (true/false)
• USE_S3_STORAGE: 是否使用S3存储 (true/false)
• 其他API密钥和配置

贡献指南

欢迎提交Pull Request或Issue来改进这个项目。

许可证

MIT

火山引擎视觉API集成

本项目集成了火山引擎（VolcEngine）的图像编辑API，实现AI驱动的图像编辑功能。

更新通知（2024年）

重要：我们已将图片编辑API升级至ByteEdit V2.0版本，并使用纯Node.js实现了API认证和调用。

API配置

需要在环境变量中配置以下变量：

VOLC_AI_IMAGE_EDIT_ACCESS_KEY_ID=您的火山引擎AccessKey
VOLC_AI_IMAGE_EDIT_SECRET_ACCESS_KEY=您的火山引擎SecretKey
VOLC_AI_IMAGE_EDIT_REQ_KEY=byteedit_v2.0

集成方式

我们实现了纯Node.js的API集成解决方案：

1. 纯Node.js实现:

   • 不依赖任何第三方SDK
   • 不需要PHP或其他语言环境
   • 简化部署和维护

2. 功能特点:

   • 支持异步任务提交与结果获取
   • 内置重试和超时处理机制
   • 完善的日志记录，便于故障排查

已知问题

火山引擎API可能返回以下认证错误：

• InvalidCredential：认证信息无效
• SignatureDoesNotMatch：签名不匹配
• InvalidAuthorization：授权头无效
• MissingRequestInfo：请求信息缺失

解决方案：

1. 确保配置了正确的AccessKey和SecretKey
2. 如持续遇到认证问题，考虑联系火山引擎技术支持获取帮助

后续提升计划

我们计划在未来版本中进行以下改进：

1. 完善签名算法，提高认证成功率
2. 改进错误处理和日志记录
3. 增加更多图像处理功能的支持
4. 添加API调用的缓存和节流控制

文本指令图像编辑平台

基于火山引擎ByteEdit V2.0 API的图像编辑平台，通过自然语言指令编辑图像。

新增功能

文本指令图像编辑功能

现已集成火山引擎最新的ByteEdit V2.0 API，支持通过自然语言描述对图像进行编辑。用户只需上传图片，输入文本提示词，即可实现复杂的图像变换。

主要特性

• 通过自然语言描述编辑图像
• 支持多种风格转换
• 背景替换和物体添加
• 可调节编辑强度和随机种子
• 查看编辑历史并重复使用成功的提示词

技术方案

前端实现

• 使用Bootstrap 5构建响应式UI
• 基于Fetch API与后端通信
• 支持图像上传、预览和结果比对
• 使用SweetAlert2实现美观的提示和确认对话框

后端实现

• 使用Node.js + Express搭建服务器
• 图片上传和处理使用Multer和Sharp
• 通过PHP桥接器调用火山引擎官方PHP SDK
• 将处理结果存储到AWS S3对象存储
• MongoDB记录编辑历史

认证问题解决方案

由于火山引擎API认证机制与Node.js SDK存在兼容性问题，我们采用了以下解决方案：

1. 使用官方PHP SDK调用API，确保认证过程正确
2. 开发Node.js与PHP的桥接器，通过子进程执行PHP脚本
3. 在服务器上安装PHP运行环境作为依赖
4. 通过临时生成PHP脚本处理请求并解析结果

安装部署

环境要求

• Node.js 14+
• PHP 7.4+
• MongoDB
• AWS S3存储桶及访问凭证

安装步骤

1. 克隆仓库

git clone https://github.com/yourusername/text-image-edit.git
cd text-image-edit

2. 安装Node.js依赖

npm install

3. 安装PHP依赖（确保已安装Composer）

cd volc-sdk-php-main
composer install

4. 配置环境变量

cp .env.example .env
# 编辑.env文件，填入相关配置

5. 启动服务

npm start