# uctoo-backend **Repository Path**: UCT/uctoo-backend ## Basic Information - **Project Name**: uctoo-backend - **Description**: uctoo 服务端应用，技术选型nodejs、Typescript、hyperexpress、RESTFul API、JWT、prisma orm、postgresql、Redis - **Primary Language**: TypeScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2024-05-04 - **Last Updated**: 2025-08-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # uctoo backend ## 项目概述 UCToo 后端服务是一个基于 Hyper Express 和 TypeScript 的高性能后端 API 服务，为 UCToo 管理系统提供数据支持和业务逻辑处理。该服务采用现代化的微服务架构理念，使用 Prisma 作为 ORM 工具，支持多种类型数据库，并提供丰富的功能模块。 uctoo backend 是采用[UCToo](https://gitee.com/uctoo/uctoo) V3 headless CMS服务端技术选型集成prisma ORM第三方开源项目，实现的一个内容管理服务器端应用程序。 配套的HarmonyOS移动端原生应用开源地址 https://gitee.com/UCT/uctooapp ### 版本 v3.0.0 Beta ## 技术栈 服务端技术选型 Hyper-express + postgreSQL + prisma ORM。Hyper-express是nodejs生态中运行效率最高的一款开发框架。postgreSQL用于保存CMS数据和内容。通过集成[prisma ORM](https://prisma.org)、[axios](https://axios-http.com/) 、[jwt](https://jwt.io/)等开源项目，以及遵循UMI全栈模型同构规范，实现云原生headless CMS的基础设施。 ## 主要功能和特性 1. 实现RBAC权限体系，采用jwt token验证API接口权限。 2. 采用prisma ORM兼容PostgreSQL/mysql/GaussDB/MongoDB等多种类型数据库。 3. 通过集成node-easywechat,可支持微信第三方平台开发。 4. 良好的容器化可支持云原生部署。 5. 遵循UMI全栈模型同构规范，兼容OpemHarmony标准化数据通路UDMF标准，实现多端一致性数据同步和多媒体内容保存、管理和分享。 6. 支持从数据库表结构生成API接口（typescript）、admin管理后台（VUE3）、小程序（uniapp）、APP（ArkTS）等全栈代码。 ## 项目结构 ``` backend/ ├── .env.example # 环境变量示例 ├── .gitignore ├── Dockerfile # Docker 配置 ├── README.md # 项目文档 ├── addons/ # 插件目录 ├── assets/ # 静态资源 ├── docker-compose.yml # Docker Compose 配置 ├── docs/ # 文档目录 ├── jest.config.js # Jest 配置 ├── merchant/ # 商户相关配置 ├── package.json # 项目依赖 ├── prisma/ # Prisma 配置和数据库模型 ├── setupTests.ts # 测试设置 ├── src/ # 源代码 │ ├── app/ # 应用代码 │ │ ├── controllers/ # 控制器 │ │ ├── helpers/ # 辅助函数 │ │ ├── lib/ # 工具库 │ │ ├── middlewares/ # 中间件 │ │ ├── routes/ # 路由 │ │ ├── services/ # 服务层 │ │ └── websocket/ # WebSocket 相关 │ ├── app.ts # 应用入口 │ ├── config.ts # 配置 │ ├── environments/ # 环境配置 │ ├── index.ts # 启动入口 │ └── interfaces/ # 接口定义 ├── ssl/ # SSL 证书 ├── storage/ # 存储目录 ├── tests/ # 测试 └── tsconfig.json # TypeScript 配置 ``` ## 核心功能模块 1. **认证与授权** - 用户登录、注册、密码重置 - 第三方登录 (GitHub, Google, 微信) - JWT 认证 - 权限控制 2. **内容管理系统 (CMS)** - 文章管理 - 分类管理 - 标签管理 - 评论管理 - 表单管理 3. **客户关系管理 (CRM)** - 客户信息管理 - 客户拜访记录 - 名片管理 4. **电商系统 (Minishop)** - 商品管理 - 订单管理 - 优惠券管理 - 购物车 - 支付集成 5. **系统管理** - 用户管理 - 角色管理 - 权限管理 - 部门管理 6. **数据统计** - 访问统计 - 业务数据统计 7. **其他功能** - 定时任务 - 文件上传下载 - WebSocket 实时通信 - 短信服务集成 ## 安装 nodejs版本建议18.x、20.x，其他版本未作兼容性测试。 ### docker部署 ### linux 需先安装docker和docker-compose。编辑 .env、docker-compose.yml 文件配置环境变量，可参考.env.example,其中DATABASE_URL配置为待新建的uctoo数据库连接信息 以下命令可参考，多数据库应用场景的prisma orm命令请参考[uctoo数据库设计规范](./docs/uctoo数据库设计规范.md) 文档： ```shell $ docker-compose build # 构建或者重新构建服务 #如果是首次运行，需新建数据库，新开一个shell窗口，执行以下命令。如连接已有数据库，则跳过此步。 # 首次运行安装的参考命令,windows环境命令相同 $ npm run createDB # 创建数据库 $ npx prisma db push --schema=prisma/postgresql/schema.prisma # 从schema.prisma生成或更新数据库，请仅在原型设计阶段使用 $ npm run uctoo:seed # 初始化数据库数据 $ npx prisma migrate dev --name init # 创建第一个迁移 # 开发流水线过程的命令参考 $ npx prisma db pull --schema=prisma/postgresql/schema.prisma # 从数据库内省生成或更新schema.prisma ,多数据库应用场景需加 --schema 参数 $ npx prisma generate # 从schema.prisma生成或更新Prisma Client $ npx prisma db push --schema=prisma/postgresql/schema.prisma # 从schema.prisma生成或更新数据库，请仅在原型设计阶段使用, push命令会自动运行generate更新client $ docker-compose up # 创建并且启动所有容器 $ docker-compose up -d # 创建并且后台运行方式启动所有容器 $ docker-compose down # 停止并删除容器，网络，图像和挂载卷 $ docker-compose build --force-rm --no-cache #构建服务删除缓存 ``` 正常启动服务后，将运行三个Container服务，一个是postgresql，在5432端口提供数据库服务。一个是后端app，在3000端口提供API服务，例如，http://domain:3000 ，如部署在公有云环境，需注意配置公有云安全规则开放3000端口访问限制。一个是redis服务，在6379端口提供缓存支持。 ### windows 需先安装WSL、docker desktop。安装、运行命令与linux环境相同。 ### 本地开发测试环境 以非docker方式部署本地开发测试环境，可参考此步骤： 1. npm install安装依赖。如遇到依赖安装超时，可通过配置国内镜像加速安装。如遇到Hyper-express安装不成功，可通过 npm i hyper-express 命令单独安装。 2. 编辑 根目录 .env文件配置API域名和ssl证书、数据库服务地址帐密等运行环境参数。 4. 项目根目录运行以上首次运行安装的参考命令。 5. npm run start 启动服务，可通过浏览器访问.env文件中配置的 API_URL/hello URL地址验证后台是否运行，API_URL//prismacheck URL地址验证数据库查询是否正常 6. npm run watch 命令可在后台驻守运行开发框架 7. npm run build 命令可编译产出物用于部署正式生产环境 8. 运行uctoo-admin PC端Web管理后台项目，可登录管理后台。初始管理员帐号为admin，密码为123456，请在CRM模块管理后台用户菜单修改初始帐密。 9. 可在管理后台->系统配置->数据库连接菜单，新增管理更多数据库。 ## 运维 ### 生产环境部署 可以使用pm2进行守护进程管理node在系统常驻运行，以下命令可参考 ```shell 1. pm2 start "npm run start" # 启动开发环境常驻运行 2. pm2 stop "npm run start" # 停止开发环境常驻运行 3. pm2 list # 列出所有正在运行的应用程序 4. pm2 status # 监控面板 ``` ## API ### API文档地址 https://apifox.com/apidoc/shared/9a22079c-a59f-4b65-a7f6-678f0643e7f6/api-170720939 可使用apifox工具打开API项目参与开发协作 ## 文档及开发规范 请参考docs目录 ## known issues 1. 部署目录中不支持包含中文 ## 版本演进 1. 本项目已较好的支持了容器化，后续通过集成公有云的云原生技术体系，可实现开发者一键开通和部署一个公有云的云开发和测试环境。 ## 技术交流 开发者交流QQ群984748053 更多信息请关注uctoo官网https://www.uctoo.com ，应用开发流水线官网 https://www.gitatom.com (开发中) ## 参考资料 UCToo https://gitee.com/uctoo/uctoo Hyper-express https://github.com/kartikk221/hyper-express node-easywechat https://github.com/hpyer/node-easywechat ArkTS https://docs.openharmony.cn/pages/v4.1/zh-cn/application-dev/arkts-utils/arkts-commonlibrary-overview.md prisma https://prisma.org ## 版权信息 本项目采用MIT开源协议发布。 本项目包含的第三方源码和二进制文件之版权信息另行标注。 版权所有Copyright © 2014-2025 UCToo (https://www.uctoo.com) All rights reserved