{"id":29112683,"url":"https://github.com/hongch666/mix-web-demo","last_synced_at":"2026-04-09T17:54:22.927Z","repository":{"id":295222738,"uuid":"989515144","full_name":"hongch666/mix-web-demo","owner":"hongch666","description":"这是一个微服务的 Demo 框架，集成了对 Spring/Gin/Nest.js/FastAPI 微服务注册与发现（Nacos），并使用 SpringCloud 的 gateway 网关进行服务路由和登录校验，可在此基础上进行项目扩展。","archived":false,"fork":false,"pushed_at":"2025-06-22T11:23:03.000Z","size":940,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-22T12:28:14.712Z","etag":null,"topics":["fastapi","gin","nestjs","spring"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hongch666.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-24T08:54:20.000Z","updated_at":"2025-06-22T11:23:06.000Z","dependencies_parsed_at":"2025-05-24T10:20:19.304Z","dependency_job_id":"23a701fb-93db-4035-91c0-5efdf206d926","html_url":"https://github.com/hongch666/mix-web-demo","commit_stats":null,"previous_names":["hongch666/mix-web-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hongch666/mix-web-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongch666%2Fmix-web-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongch666%2Fmix-web-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongch666%2Fmix-web-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongch666%2Fmix-web-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hongch666","download_url":"https://codeload.github.com/hongch666/mix-web-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongch666%2Fmix-web-demo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262581282,"owners_count":23331908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","gin","nestjs","spring"],"created_at":"2025-06-29T11:02:05.708Z","updated_at":"2026-04-09T17:54:22.884Z","avatar_url":"https://github.com/hongch666.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 基于 RAG 知识问答与 LLM 驱动推荐的 IT 智能文章推荐与知识问答系统(多语言技术栈构建)\n\n![Java](https://img.shields.io/badge/Java-17+-red?logo=java\u0026logoColor=white)\n![Spring](https://img.shields.io/badge/Spring-Boot-6DB33F?logo=spring\u0026logoColor=white)\n![Go](https://img.shields.io/badge/Go-1.23+-00ADD8?logo=go\u0026logoColor=white)\n![GoZero](https://img.shields.io/badge/GoZero-Framework-00ADD8?logo=go\u0026logoColor=white)\n![Node.js](https://img.shields.io/badge/Node.js-20+-339933?logo=node.js\u0026logoColor=white)\n![NestJS](https://img.shields.io/badge/NestJS-Framework-E0234E?logo=nestjs\u0026logoColor=white)\n![Python](https://img.shields.io/badge/Python-3.12+-3776AB?logo=python\u0026logoColor=white)\n![FastAPI](https://img.shields.io/badge/FastAPI-Framework-009688?logo=fastapi\u0026logoColor=white)\n\n## 目录\n\n\u003cdetails\u003e\n\u003csummary\u003e点击展开目录\u003c/summary\u003e\n\n- [描述](#描述)\n- [功能说明](#功能说明)\n- [设计图](#设计图)\n- [技术栈](#技术栈)\n- [第三方服务](#第三方服务)\n- [环境要求](#环境要求)\n- [环境设置](#环境设置)\n- [环境配置脚本](#环境配置脚本)\n- [Docker 基础中间件容器部署](#docker-基础中间件容器部署)\n- [编译和运行项目](#编译和运行项目)\n- [测试说明](#测试说明)\n- [运行脚本配置](#运行脚本配置)\n- [生产环境部署](#生产环境部署)\n- [Docker 容器部署](#docker-容器部署)\n- [Docker Compose 部署](#docker-compose-部署)\n- [基础服务组件初始化](#基础服务组件初始化)\n- [环境变量配置文件](#环境变量配置文件)\n- [Swagger 说明](#swagger-说明)\n- [项目规范说明](#项目规范说明)\n- [项目可用工具说明](#项目可用工具说明)\n- [其他说明](#其他说明)\n- [许可证](#许可证)\n\n\u003c/details\u003e\n\n## 描述\n\n这是一个基于多语言技术栈构建的 IT 智能文章推荐与知识问答系统，主要包含以下框架：\n\n- Spring（Java）\n- GoZero（Go）\n- NestJS（Node.js）\n- FastAPI（Python）\n\n所有服务通过 SpringCloud Gateway 统一网关进行访问，实现了服务治理、认证授权等功能。\n\n[前端对应仓库地址](https://gitee.com/chu-shichao/react-web-demo)\n\n## 功能说明\n\n1. 基于 Spring Boot 和 MybatisPlus 实现文章发布、修改等操作，文章的创建和显示都支持 Markdown\n2. 基于 Spring Boot 和 MybatisPlus 实现用户、分类、评论、点赞、收藏、关注等业务模块\n3. 基于 Spring Boot 和 Redis 进行文章分类，用户状态的管理操作\n4. 基于 Spring Boot 和 AOP 技术权限校验实现用户端和管理端\n5. 基于 GoZero 和 ElasticSearch 进行搜索引擎式文章搜索\n6. 基于 GoZero 和 GORM 实现文章相关数据获取和同步\n7. 基于 GoZero 和 WebSocket/SSE 实现用户实时聊天功能和消息通知\n8. 基于 NestJS 和 Mongoose 进行文章操作日志和 API 日志的查看和分析\n9. 基于 NestJS 和 TypeORM 实现文章下载的文章和用户数据获取\n10. 基于 FastAPI 和 ClickHouse 技术栈实现系统数据的相关分析\n11. 基于 FastAPI 和 SQLAlchemy 进行文章相关数据的获取和同步\n12. 基于 FastAPI 和 LangChain 实现 RAG 文章检索增强和 Tools 调用 SQL 和 MongoDB，支持 **豆包/Gemini/Qwen** 进行多模型选择\n\n## 设计图\n\n- 系统架构图\n\n  ![architecture](./static/pic/architecture.drawio.png)\n\n- ER 图\n\n  ![er](./static/pic/er.drawio.png)\n\n## 技术栈\n\n- Spring Boot：Java 后端框架，支撑系统核心业务服务\n- GoZero：Golang 后端框架，支持系统高并发服务\n- NestJS：Node.js 后端框架，支撑系统日志处理服务\n- FastAPI：Python 后端服务，支撑系统数据分析和 Agent 服务\n- Spring Cloud Gateway：API 网关\n- JWT：身份验证\n- Nacos：服务发现与配置中心\n- MySQL：关系型数据库，系统核心数据库\n- PostgreSQL：RAG 向量数据库\n- MongoDB：非关系型数据库，系统日志数据库\n- ElasticSearch：搜索引擎，系统搜索优化\n- Redis：缓存服务和状态管理\n- RabbitMQ：异步消息队列\n- ClickHouse：大数据存储与分析\n- WebSocket：用户实时聊天\n- SSE：实时通知未读消息\n- LangChain：大模型调用和 RAG 框架\n\n## 第三方服务\n\n- [火山引擎](https://www.volcengine.com/)\n- [阿里云百炼平台](https://bailian.console.aliyun.com/)\n- [Close AI](https://platform.closeai-asia.com/dashboard)\n- [阿里云 OSS](https://oss.console.aliyun.com/overview)\n\n## 环境要求\n\n- Java 17+\n- Maven 3.6+\n- Gradle 9.3+(可选，但推荐用于 Java 项目构建)\n- Go 1.23+\n- Node.js 20+\n- Bun 1.2+(可选)\n- Python 3.12+\n- uv 0.9+(可选)\n- MySQL 8.0+\n- PostgreSQL + pgvector 15.4+\n- MongoDB 5.0+\n- ElasticSearch 7.12.1+\n- Redis 6.0+\n- RabbitMQ 3.8+\n- ClickHouse 21.8+(可选)\n\n## 环境设置\n\n\u003e **提示**: 推荐使用 `setup.sh` 配置脚本自动完成以下所有安装步骤。\n\u003e\n\u003e 如果需要手动配置，可以按照下面的步骤逐个模块进行。\n\n### Spring 部分\n\n```bash\ncd spring # 进入文件夹\ncd gateway # 进入网关\nmvn clean install # 下载依赖\ngradle wrapper # 生成项目专用 Gradle，运行自动下载依赖\n```\n\n### GoZero 部分\n\n```bash\ncd gozero/app # 进入文件夹\ngo mod tidy # 安装依赖\ngo install github.com/zeromicro/go-zero/tools/goctl@latest # 安装 goctl 代码生成工具\n```\n\n### NestJS 部分\n\n```bash\ncd nestjs # 进入文件夹\nnpm install # 安装npm包\nbun install # 或者使用bun安装\n```\n\n### FastAPI 部分\n\n```bash\n# 使用标准 venv 和 requirements.txt\ncd fastapi\n# 创建虚拟环境\npython3 -m venv venv\n# 激活虚拟环境\nsource venv/bin/activate\n# 安装依赖\npip install -r requirements.txt\n\n# 使用 uv 进行项目管理\ncd fastapi\n# 配置 uv 虚拟环境\nuv venv --python /usr/bin/python3.11 # 创建虚拟环境时指定 Python\n# 激活虚拟环境\nsource .venv/bin/activate\n# 同步依赖（可以使用国内镜像）\nuv sync\n```\n\n\u003e 项目使用 uv 进行依赖管理，配置文件为 `pyproject.toml`。镜像源配置在 `~/.config/uv/uv.toml`，内容如下\n\n```toml\n[[index]]\nname = \"aliyun\"\nurl = \"https://mirrors.aliyun.com/pypi/simple\"\ndefault = true\n\n```\n\n## 环境配置脚本\n\n为了简化项目初始化过程，我们提供了自动化配置脚本 `scripts/setup.sh`，可以自动检测环境、安装依赖并配置所有模块。\n\n### Linux/macOS 使用方式\n\n```bash\n# 1. 使用便捷脚本调用（推荐）\n./mix setup\n\n# 或直接调用\n./scripts/setup.sh\n```\n\n### 交互式配置\n\n运行脚本后会出现以下交互界面：\n\n```bash\n# 根据提示选择要配置的模块\n# 选项:\n# 1) Spring      - 配置 Spring Boot 服务\n# 2) GoZero      - 配置 GoZero 服务\n# 3) NestJS      - 配置 NestJS 服务\n# 4) FastAPI     - 配置 FastAPI 服务\n# 5) 全部        - 配置所有模块\n```\n\n### 脚本功能特性\n\n1. **环境检查**\n   - 自动检测 Python、Go、Java、Node.js 等必要工具的安装状态和版本\n   - 如果缺少必要工具会给出明确提示\n\n2. **系统依赖管理**（仅 FastAPI 模块需要）\n   - 自动检测并安装 PostgreSQL 开发库（`libpq-dev`）\n   - 自动安装编译工具（`build-essential`、`python3-dev`）\n   - 支持多种 Linux 发行版（Ubuntu/Debian、CentOS/RHEL、Fedora、Arch）\n\n3. **模块化安装**\n   - 支持选择性安装特定模块或全部安装\n   - 每个模块独立配置，互不影响\n\n4. **智能判断**\n   - Spring: 自动检测是否有全局 Gradle 和 Maven，优先使用 Gradle（若两者都存在）；同时安装两者的依赖以确保完整性\n   - Gateway: 支持 Gradle 和 Maven 两种构建工具\n\n- GoZero: 自动安装 goctl（API/ORM 代码生成工具、API-First 方式代码生成和 Swagger 文档生成工具）\n- FastAPI: 自动安装 uv 并自动创建 uv 虚拟环境并使用阿里镜像源加速安装\n\n5. **目录自动创建**\n\n- 自动创建 logs 目录（spring、gozero、nestjs、fastapi）\n- 自动创建 static 目录（pic、excel、word）\n\n### 脚本执行流程\n\n```bash\n./mix setup\n```\n\n执行后将按以下流程进行：\n\n1. **检测操作系统** - 识别当前 Linux 发行版\n2. **检查环境** - 验证必要工具（Python、Go、Java、Node.js、npm）\n3. **创建目录** - 自动创建日志和静态文件目录\n4. **选择模块** - 交互式选择要配置的模块\n5. **安装依赖** - 根据选择自动安装各模块依赖\n6. **完成提示** - 显示后续配置步骤\n\n### 注意事项\n\n- **首次运行**: 建议首次配置时选择\"全部\"选项，确保所有依赖都正确安装\n- **系统权限**: 安装系统依赖时可能需要 sudo 权限\n- **网络要求**:\n  - Go 模块需要访问 GitHub 和 Go 代理\n  - Python 使用 uv 配置项目环境，使用阿里镜像源，国内访问速度较快\n  - npm 使用默认源，建议配置国内镜像（如淘宝镜像）\n- **虚拟环境**: FastAPI 会使用 uv 自动创建虚拟环境（venv），无需手动创建\n\n### 配置完成后\n\n脚本执行完成后，还需要：\n\n1. **配置各服务的环境变量文件**（见下方\"配置文件说明\"章节，先参考 `.env.example` 生成本地 `.env`，Docker 则使用 `.env.docker`）\n2. **启动基础服务**（MySQL、Redis、MongoDB、ElasticSearch、RabbitMQ、Nacos）\n3. **使用运行脚本启动服务**（见\"运行脚本配置\"章节）\n\n## Docker 基础中间件容器部署\n\n项目提供了基础依赖容器部署脚本，用于快速创建和管理 MySQL、PostgreSQL、Redis、MongoDB、ElasticSearch、Nacos 和 RabbitMQ 等服务，供下方微服务部署使用。\n\n### 基础容器部署命令\n\n`mix docker-services` 用于创建、启动、查看和清理基础中间件容器；下面的 `Docker 容器部署` 章节才是应用服务编排内容。\n\n```bash\n# 创建所有容器\n./mix docker-services up\n\n# 查看容器状态\n./mix docker-services status\n\n# 查看容器日志\n./mix docker-services logs \u003cservice\u003e\n\n# 停止所有容器\n./mix docker-services stop\n\n# 删除所有容器\n./mix docker-services delete\n\n# 显示帮助信息\n./mix docker-services help\n```\n\n### 创建的容器服务\n\n脚本会自动创建以下 Docker 容器（密码均为默认值，可通过 `.env` 文件自定义）：\n\n| 服务              | 端口        | 用户名   | 默认密码 | 说明                     |\n| ----------------- | ----------- | -------- | -------- | ------------------------ |\n| **MySQL**         | 3306        | root     | 123456   | 关系型数据库             |\n| **PostgreSQL**    | 5432        | postgres | 123456   | 向量数据库(含 pgvector)  |\n| **Redis**         | 6379        | -        | 123456   | 缓存服务                 |\n| **MongoDB**       | 27017       | root     | 123456   | 非关系型数据库           |\n| **ClickHouse**    | 8123, 9002  | hcsy     | 123456   | 大数据分析数据库         |\n| **ElasticSearch** | 9200, 9300  | -        | -        | 搜索引擎(7.12.1)         |\n| **Nacos**         | 8848, 9848  | -        | -        | 服务发现与配置中心       |\n| **RabbitMQ**      | 5672, 15672 | hcsy     | 123456   | 消息队列(管理界面 15672) |\n\n### 自定义密码配置\n\n所有容器密码均支持通过项目根目录 `.env` 文件自定义，脚本会优先读取 `.env` 中的变量，未设置时使用默认值：\n\n```bash\n# .env 文件示例\nDB_PASSWORD=你的数据库密码          # MySQL 和 PostgreSQL 密码\nREDIS_PASSWORD=你的Redis密码        # Redis 密码\nMONGO_PASSWORD=你的MongoDB密码      # MongoDB 密码\nCLICKHOUSE_USER=hcsy               # ClickHouse 用户名\nCLICKHOUSE_PASSWORD=你的密码        # ClickHouse 密码\nRABBITMQ_USER=hcsy                 # RabbitMQ 用户名\nRABBITMQ_PASSWORD=你的密码          # RabbitMQ 密码\n```\n\n### 数据持久化目录\n\n| 服务          | 宿主机目录                                     |\n| ------------- | ---------------------------------------------- |\n| MySQL         | `~/mysql/data`, `~/mysql/conf`, `~/mysql/init` |\n| PostgreSQL    | `~/pgdata`                                     |\n| Redis         | `~/redis_data`                                 |\n| MongoDB       | `~/mongo_data`                                 |\n| ClickHouse    | `~/clickhouse/data`, `~/clickhouse/logs`       |\n| ElasticSearch | Docker Volume: `es-data`, `es-plugins`         |\n| RabbitMQ      | Docker Volume: `mq-plugins`                    |\n\n### 注意事项\n\n- **首次创建**: 首次执行 `docker-services up` 时会自动创建 Docker 网络 `hcsy` 和所有数据持久化目录\n- **数据持久化**: 所有容器的数据都会持久化到宿主机目录\n- **密码配置**: 建议在 `.env` 文件中统一配置密码，避免使用默认密码\n- **ElasticSearch**: 首次创建后会提示是否安装 IK 分词器（可选）\n- **ClickHouse**: 端口 9002 映射到容器内 9000（避免与其他服务冲突），需设置 `ulimit nofile=262144`\n- **Nacos**: 自动生成 `nacos/custom.env` 配置文件，MySQL 密码与 `DB_PASSWORD` 同步\n- **权限问题**: 如果遇到权限错误，可能需要使用 `sudo` 或将用户加入 docker 组\n- 如果有额外创建的组件，按照个人的配置改动配置文件\n\n## 编译和运行项目\n\n\u003e 每个服务都可以独立运行：\n\n### Spring 服务（包括 gateway 网关）\n\n**使用 Maven 运行**：\n\n```bash\n# 运行Spring服务\ncd spring\nmvn clean install # 构建项目\nmvn spring-boot:run # 启动项目\n\n# 运行网关服务\ncd gateway\nmvn clean install # 构建项目\nmvn spring-boot:run # 启动项目\n```\n\n**使用 Gradle 运行（推荐）**：\n\n```bash\n# 运行Spring服务\ncd spring\ngradle bootRun # 启动项目\n\n# 网关服务\ncd gateway\ngradle bootRun # 启动项目\n```\n\n### GoZero 服务\n\n```bash\n# 运行 GoZero 服务\ncd gozero/app\ngo build -o bin/gozero main.go # 构建项目\ngo run main.go # 运行项目\n```\n\n### NestJS 服务\n\n**使用 npm 运行**：\n\n```bash\n# 运行NestJS服务\ncd nestjs\nnpm run node:start # npm development 模式运行\nnpm run node:start:dev # npm watch 模式运行\nnpm run node:start:debug # npm debug 模式运行\nnpm run node:start:prod # npm production 模式运行\n```\n\n**使用 bun 运行**：\n\n```bash\ncd nestjs\nnpm run bun:start # bun 运行\nnpm run bun:dev # bun watch 模式运行\nnpm run bun:prod # bun production 模式运行\n```\n\n### FastAPI 服务\n\n**使用 venv 运行**：\n\n```bash\n# 运行FastAPI服务\ncd fastapi\nsource venv/bin/activate # 激活虚拟环境\npython main.py\n```\n\n**使用 uv 运行**：\n\n```bash\n# 运行FastAPI服务\ncd fastapi\nuv run python main.py\n\n# 或指定 Python 版本\nuv run --python 3.12 python main.py\n```\n\n## 测试说明\n\n本项目按服务拆分测试代码，各服务的测试入口和运行方式如下。\n\n### 测试运行方式\n\n1. Spring\n\n```bash\ncd spring\nmvn test\n```\n\n只运行某个测试：\n\n```bash\nexport INTERNAL_TOKEN_TEST_TOKEN=实际Token\ncd spring\nmvn -Dtest=InternalTokenUtilTest test\n```\n\n2. GoZero\n\n```bash\ncd gozero/app\ngo test ./...\n```\n\n只运行某个测试：\n\n```bash\nexport INTERNAL_TOKEN_TEST_TOKEN=实际Token\ncd gozero/app\ngo test ./common/utils -run 'TestGenerateInternalToken|TestValidateInternalToken' -v\n```\n\n3. NestJS\n\n```bash\ncd nestjs\nnpm test\n```\n\n只运行某个测试：\n\n```bash\nexport INTERNAL_TOKEN_TEST_TOKEN=实际Token\ncd nestjs\nnpx jest src/common/utils/internalToken.util.spec.ts\n```\n\n4. FastAPI\n\n```bash\ncd fastapi\npytest\n```\n\n只运行某个测试：\n\n```bash\nexport INTERNAL_TOKEN_TEST_TOKEN=实际Token\ncd fastapi\npytest tests/core/auth/test_internal_token.py\n```\n\n### 测试代码规范\n\n1. **Spring**：测试文件放在 `spring/src/test/java` 下，命名建议使用 `*Test.java`。\n2. **GoZero**：测试文件放在同包目录下，命名使用 `_test.go`，测试函数使用 `TestXxx`。\n3. **NestJS**：测试文件放在 `nestjs/src` 下，命名使用 `*.spec.ts`，默认使用 Jest。\n4. **FastAPI**：测试文件放在 `fastapi/tests` 下，命名使用 `test_*.py`，默认使用 pytest。\n5. **其他说明**：生成测试参数可以写死在代码中，但是敏感信息的参数建议使用环境变量提供。\n\n## 运行脚本配置\n\n所有运行脚本已组织到 `scripts/` 目录中，便于项目管理和维护。\n\n### 快速启动（推荐）\n\n#### Linux/macOS\n\n```bash\n# 查看帮助信息\n./mix help\n\n# ===== 开发环境 =====\n# 使用多窗格 tmux 布局启动所有服务（推荐用于开发调试）\n./mix multi\n\n# 使用顺序窗口模式启动所有服务\n./mix seq\n\n# 停止所有 tmux 服务\n./mix stop\n\n# ===== Seq 模式下使用指定构建工具启动服务 =====\n# 使用 Gradle 构建并启动 Java 服务（推荐，更快）\n./mix seq --java-build gradle\n\n# 使用 Maven 构建并启动 Java 服务\n./mix seq --java-build maven\n\n# 使用 Bun 启动 NestJS 服务（推荐，比 npm 快）\n./mix seq --node-runtime bun\n\n# 使用 npm 启动 NestJS 服务\n./mix seq --node-runtime npm\n\n# 使用 UV 启动 FastAPI 服务（推荐，比 python 快）\n./mix seq --python-runtime uv\n\n# 使用 Python 启动 FastAPI 服务\n./mix seq --python-runtime python\n\n# 交互式模式：让用户选择构建工具\n./mix seq -i\n\n# ===== GoZero 代码生成 =====\n./mix goctl-api\n./mix goctl-orm\n\n# ===== Docker 容器环境 =====\n# 构建并启动所有微服务容器\n./mix docker up\n\n# 构建并启动特定服务容器\n./mix docker up spring gozero\n\n# 仅构建镜像\n./mix docker build\n\n# 推送所有镜像到远程仓库\n./mix docker push --prefix docker.io/yourname\n\n# 推送指定服务镜像到远程仓库\n./mix docker push --prefix registry.example.com/team --tag v1.0.0 spring gozero\n\n# 查看容器状态\n./mix docker status\n\n# 查看容器日志\n./mix docker logs spring\n\n# 停止所有容器\n./mix docker stop\n\n# ===== 生产环境 =====\n# 构建所有服务到 dist/ 目录\n./mix build\n\n# 启动所有已构建的服务（后台运行）\n./mix start\n\n# 启动指定的服务\n./mix start spring gateway\n./mix start fastapi gozero\n\n# 查看已构建服务的运行状态\n./mix status\n\n# 查看指定服务的运行状态\n./mix status spring gozero\n\n# 重启所有已构建的服务\n./mix restart\n\n# 重启指定的服务\n./mix restart fastapi\n./mix restart spring gateway nestjs\n\n# 停止所有已构建的服务\n./mix stop-dist\n\n# 停止指定的服务\n./mix stop-dist spring fastapi\n\n# 查看服务的最新日志（只支持查看单个服务）\n./mix logs spring\n./mix logs fastapi\n./mix logs gozero\n```\n\n**构建工具参数说明**：\n\n- `--java-build gradle|maven`：选择 Java 构建工具（Spring/Gateway）\n  - `gradle`：使用 Gradle（推荐，更快）\n  - `maven`：使用 Maven（可选）\n  - 默认值：`gradle`（如果已安装）\n\n- `--node-runtime bun|npm`：选择 Node.js 运行时（NestJS）\n  - `bun`：使用 Bun（推荐，比 npm 快 4-8 倍）\n  - `npm`：使用 npm（可选）\n  - 默认值：`bun`（如果已安装）\n\n- `--python-runtime uv|python`：选择 Python 运行时（FastAPI）\n  - `uv`：使用 UV（推荐，更快且支持虚拟环境）\n  - `python`：使用原生 Python（可选）\n  - 默认值：`uv`（如果已安装）\n\n- `-i`/`--interactive`：交互式模式，让用户选择每个服务的工具\n\n#### Windows\n\n```powershell\n# 启动所有服务（PowerShell）\nPowerShell -ExecutionPolicy Bypass -File .\\scripts\\run.ps1\n```\n\n### 直接调用脚本\n\n如果需要直接调用 `scripts/` 目录下的脚本：\n\n#### Linux/macOS\n\n```bash\n# 启动服务（多窗格布局） - 使用 Gradle 构建\n./scripts/run_multi.sh\n\n# 或指定构建工具参数（推荐）\n./scripts/run.sh --java-build gradle --node-runtime bun --python-runtime uv\n\n# 启动服务（顺序窗口布局）\n./scripts/run.sh\n\n# 交互式选择工具\n./scripts/run.sh -i\n\n# 停止所有服务\n./scripts/stop.sh\n\n# 构建所有服务\n./scripts/build.sh\n\n# 管理分布式部署的服务\n\n# 启动所有服务或指定服务\n./scripts/dist-control.sh start              # 启动所有\n./scripts/dist-control.sh start spring gozero   # 启动指定\n\n# GoZero 代码生成\n./scripts/goctl-api-init.sh\n./scripts/goctl-orm-init.sh\n\n# 停止所有服务或指定服务\n./scripts/dist-control.sh stop               # 停止所有\n./scripts/dist-control.sh stop fastapi       # 停止指定\n\n# 查看所有服务状态或指定服务状态\n./scripts/dist-control.sh status             # 查看所有\n./scripts/dist-control.sh status spring      # 查看指定\n\n# 重启所有服务或指定服务\n./scripts/dist-control.sh restart            # 重启所有\n./scripts/dist-control.sh restart nestjs     # 重启指定\n\n# 查看单个服务的最新日志\n./scripts/dist-control.sh logs spring\n./scripts/dist-control.sh logs fastapi\n```\n\n**run.sh 脚本参数**：\n\n| 参数                   | 选项               | 说明                                             |\n| ---------------------- | ------------------ | ------------------------------------------------ |\n| `--java-build`         | `gradle` / `maven` | Java 项目构建工具（Spring/Gateway），默认 gradle |\n| `--node-runtime`       | `bun` / `npm`      | Node.js 运行时（NestJS），默认 bun               |\n| `--python-runtime`     | `uv` / `python`    | Python 运行时（FastAPI），默认 uv                |\n| `-i` / `--interactive` | 无                 | 交互式模式，提示用户选择各服务的工具             |\n| `-h` / `--help`        | 无                 | 显示帮助信息                                     |\n\n示例：\n\n```bash\n# 使用 Maven 和 npm 启动\n./scripts/run.sh --java-build maven --node-runtime npm\n\n# 使用 Python 启动 FastAPI\n./scripts/run.sh --python-runtime python\n\n# 交互式选择\n./scripts/run.sh --interactive\n```\n\n#### Windows\n\n```powershell\n# 启动所有服务\n.\\scripts\\run.ps1\n```\n\n### 脚本说明\n\n| 脚本                    | 位置       | 功能                                       | 适用系统    |\n| ----------------------- | ---------- | ------------------------------------------ | ----------- |\n| `mix`                   | 项目根目录 | 便捷启动器，用于快速调用 scripts/ 下的脚本 | Linux/macOS |\n| `run_multi.sh`          | scripts/   | 使用 tmux 多窗格布局启动所有服务（推荐）   | Linux/macOS |\n| `run.sh`                | scripts/   | 使用 tmux 顺序窗口模式启动所有服务         | Linux/macOS |\n| `stop.sh`               | scripts/   | 停止所有 tmux 服务                         | Linux/macOS |\n| `build.sh`              | scripts/   | 编译所有服务到 dist/ 目录                  | Linux/macOS |\n| `dist-control.sh`       | scripts/   | 管理打包后的分布式服务（支持服务指定）     | Linux/macOS |\n| `docker-push-images.sh` | scripts/   | 将已构建的 Docker 镜像推送到远程仓库       | Linux/macOS |\n| `setup.sh`              | scripts/   | 环境初始化和依赖安装                       | Linux/macOS |\n| `swag-init.sh`          | scripts/   | 生成 GoZero Swagger 文档                   | Linux/macOS |\n| `goctl-api-init.sh`     | scripts/   | 生成 GoZero API 代码                       | Linux/macOS |\n| `goctl-orm-init.sh`     | scripts/   | 生成 GoZero ORM 代码                       | Linux/macOS |\n| `run.ps1`               | scripts/   | PowerShell 脚本，启动所有服务              | Windows     |\n\n### 服务名称\n\ndist-control.sh 和 mix 支持以下服务名称：\n\n- `spring` - Spring Boot 服务\n- `gateway` - Spring Cloud Gateway 网关服务\n- `fastapi` - FastAPI 服务\n- `gozero` - GoZero 服务\n- `nestjs` - NestJS 服务\n\n如不指定服务名称，则对所有服务进行操作。\n\n### 注意事项\n\n1. **tmux 依赖**：Linux/macOS 脚本依赖 `tmux`，请确保已安装\n2. **执行权限**：Linux/macOS 脚本需要执行权限，可以通过 `chmod +x scripts/*.sh` 来设置\n3. **相对路径**：所有脚本都使用相对路径，可以在任何目录下调用项目的脚本\n4. **服务依赖**：启动前请确保 MySQL、Redis、MongoDB、ElasticSearch、RabbitMQ、Nacos 等基础服务已运行\n5. **logs 命令**：仅支持查看单个服务的日志，如需查看多个服务请依次调用\n\n## 生产环境部署\n\n本项目提供了统一的打包和部署脚本，可以一键打包所有微服务并统一管理。\n\n**方法一：使用便捷脚本**\n\n```bash\n# 1. 一键打包所有服务\n./mix build\n\n# 2. 启动所有服务\n./mix start\n\n# 3. 查看服务状态\n./mix status\n\n# 4. 重启所有服务（代码更新后）\n./mix restart\n\n# 5. 停止所有服务\n./mix stop-dist\n```\n\n**方法二：直接调用脚本**\n\n```bash\n# 1. 一键打包所有服务\n./scripts/build.sh\n\n# 2. 启动所有服务\n./scripts/dist-control.sh start\n\n# 3. 查看服务状态\n./scripts/dist-control.sh status\n\n# 4. 重启所有服务\n./scripts/dist-control.sh restart\n\n# 5. 停止所有服务\n./scripts/dist-control.sh stop\n```\n\n打包后的文件统一位于 `dist/` 目录，每个服务都包含配置文件、启动/停止脚本和日志文件。\n\n### 脚本说明\n\n- **mix**（项目根目录）\n  - 便捷启动器，用于快速调用 `scripts/` 下的脚本\n  - 支持开发环境和生产环境命令\n\n- **scripts/build.sh**\n  - 编译所有服务：Spring、Gateway、FastAPI、GoZero、NestJS\n  - 将编译结果打包到 `dist/` 目录\n  - 包含编译错误检查和日志输出\n\n- **scripts/dist-control.sh**\n  - 管理打包后的分布式服务\n  - 支持的操作：`start`、`stop`、`status`、`restart`、`logs`\n\n## Docker 容器部署\n\n项目提供了完整的 Docker 支持，可以为每个微服务构建镜像并创建容器。\n\n### 微服务 Docker 快速开始\n\n```bash\n# 1. 构建并启动所有微服务容器\n./mix docker up\n\n# 2. 查看容器状态\n./mix docker status\n\n# 3. 查看特定服务的日志\n./mix docker logs spring\n\n# 4. 停止所有微服务容器\n./mix docker stop\n```\n\nDocker 环境会优先读取每个服务目录下的 `.env.docker`，不会自动创建该文件。请根据需要手动准备 Docker 专用环境变量文件，本地开发仍然使用 `.env`。\n\nDocker 启动时会把所有应用容器接入同一个 `hcsy` 网络，容器间地址请使用服务名：\n\n- `gateway` -\u003e `8080`\n- `spring` -\u003e `8081`\n- `gozero` -\u003e `8082`\n- `nestjs` -\u003e `8083`\n- `fastapi` -\u003e `8084`\n\n基础组件在同一网络中的服务名为：\n\n- `mysql`\n- `redis`\n- `mongodb`\n- `es`\n- `nacos`\n- `mq`\n- `pgvector-db`\n- `clickhouse`\n\n### 微服务容器说明\n\n| 服务        | 端口 | 镜像名称             | 容器名称                | 技术栈           |\n| ----------- | ---- | -------------------- | ----------------------- | ---------------- |\n| **Gateway** | 8080 | `mix-gateway:latest` | `mix-gateway-container` | Java 17 + Alpine |\n| **Spring**  | 8081 | `mix-spring:latest`  | `mix-spring-container`  | Java 17 + Alpine |\n| **GoZero**  | 8082 | `mix-gozero:latest`  | `mix-gozero-container`  | Go 1.23 + Alpine |\n| **NestJS**  | 8083 | `mix-nestjs:latest`  | `mix-nestjs-container`  | Node 20 + Alpine |\n| **FastAPI** | 8084 | `mix-fastapi:latest` | `mix-fastapi-container` | Python 3.12      |\n\n### 高级用法\n\n```bash\n# 仅构建特定服务的镜像\n./mix docker build spring gozero\n\n# 仅构建镜像，不启动容器\n./scripts/build_and_run_services.sh --build-only\n\n# 手动启动容器时指定配置文件\ndocker run -d --name mix-spring-custom \\\n  --network hcsy \\\n  -p 8081:8081 \\\n  -v $(pwd)/spring/application.yaml:/app/application.yaml \\\n  -v $(pwd)/spring/application-secret.yaml:/app/application-secret.yaml \\\n  mix-spring:latest\n\n# 查看容器日志\ndocker logs -f mix-spring-container\n\n# 进入容器交互式终端\ndocker exec -it mix-spring-container bash\n\n# 重启容器（应用新配置）\ndocker restart mix-spring-container\n```\n\n## Docker Compose 部署\n\n目前 `docker-compose.yml` 仅包含 5 个应用服务：\n\n- gateway\n- spring\n- gozero\n- nestjs\n- fastapi\n\n第三方依赖（MySQL/Redis/MongoDB/ES/Nacos/RabbitMQ/ClickHouse）请继续使用现有启动脚本（如 `./scripts/docker-services.sh`），并确保它们与同一 Docker 网络 `hcsy` 运行。\n\n应用容器镜像将由 `./mix docker build` 生成：\n\n```bash\n./mix docker build gateway spring gozero nestjs fastapi\n```\n\n为了与 `mix docker` 启动一致，`docker-compose` 会挂载以下配置与日志目录：\n\n- `spring/application.yaml -\u003e /app/application.yaml`\n- `gozero/etc -\u003e /app/etc`\n- `nestjs/application.yaml -\u003e /app/application.yaml`\n- `fastapi/application.yaml -\u003e /app/application.yaml`\n- `logs/\u003cservice\u003e -\u003e /app/logs/\u003cservice\u003e`\n- `static/pic`, `static/excel`, `static/upload`\n\n`./scripts/docker-compose-up.sh` 已自动创建目录并设置可写权限，避免 `ENOENT application.yaml` 与 `permission denied` 问题。\n\n建议先构建镜像，再启动 Compose。\n\n### 前置要求\n\n- **Docker**：\u003e= 20.10\n- **docker-compose**：或使用 `docker compose` (Docker CLI 集成)\n\n### 启动服务\n\n```bash\n# 启动依赖服务（如果尚未启动）\n./scripts/docker-services.sh\n\n# 启动应用服务（5 个）\n./mix compose up\n```\n\n### 停止服务\n\n```bash\n./mix compose down\n```\n\n### 状态查看\n\n```bash\n./mix compose status\n```\n\n### 查看日志\n\n```bash\n./mix compose logs \u003cservice\u003e\n```\n\n### 手动命令（可选）\n\n```bash\ndocker-compose up -d --build\ndocker-compose down -v\n```\n\n### 文件说明\n\n- `docker-compose.yml`：整套应用编排（数据库、缓存、消息队列、服务容器）\n- `scripts/docker-compose-up.sh`：快速启动脚本\n- `scripts/docker-compose-down.sh`：快速停止脚本\n\n### 访问服务\n\n服务启动后可直接访问本地端口：\n\n- Gateway: http://localhost:8080\n- Spring: http://localhost:8081\n- GoZero: http://localhost:8082\n- NestJS: http://localhost:8083\n- FastAPI: http://localhost:8084\n\n### 高级用法\n\n```bash\n# 查看某个服务实时日志\n./mix compose logs spring\n\n# 查看所有服务状态\n./mix compose status\n\n# 重启某个服务（可配合 docker-compose restart）\ncd /home/hongch666/mix-web-demo\nsudo docker-compose -f docker-compose.yml restart spring\n\n# 进入容器调试\nsudo docker exec -it mix-spring /bin/bash\n\n# 清理未用镜像与容器\ndocker system prune -af\n```\n\n## 基础服务组件初始化\n\n### 确保已安装并启动以下数据库服务：\n\n- MySQL\n- PostgreSQL\n  - 需要安装 `pgvector`插件\n- MongoDB\n- Redis\n- ElasticSearch\n- RabbitMQ\n- Nacos\n\n### SQL 初始化脚本说明\n\n项目的 SQL 初始化脚本已经统一迁移到根目录的 `db/` 目录下，按数据库类型拆分管理。\n\n- `db/mysql/`：MySQL 建表脚本，按表拆分为独立文件\n- `db/postgresql/`：PostgreSQL 初始化脚本，主要用于扩展启用\n- `db/clickhouse/`：ClickHouse 初始化脚本，主要用于映射库和物化视图\n\n建议执行顺序如下：\n\n1. 先执行 `db/mysql/` 下的建表脚本\n2. 再执行 `db/postgresql/` 下的扩展脚本\n3. 最后执行 `db/clickhouse/` 下的同步脚本\n\n如果后续新增数据库初始化内容，也请继续放到 `db/` 下对应的数据库目录中，便于统一维护和查找\n\n### MySQL 表创建\n\n系统服务会自动创建，也可以先执行 `db/mysql/` 下的SQL脚步创建基础表结构\n\n### PostgreSQL 表创建\n\nLangChain 会自动创建，但需要先执行 `db/postgresql/extensions.sql` 启用 `pgvector` 扩展\n\n### MongoDB 表创建\n\n数据库为 `demo`，集合为 `articlelogs`和 `apilogs`，系统会自动创建\n\n### ElasticSearch 索引创建\n\n无需创建，系统同步数据时会自动创建\n\n### ClickHouse 创建\n\n需要先执行 `db/clickhouse/articles_sync.sql`，其中包含 MySQL 映射库、本地表和物化视图的创建语句\n\n## 环境变量配置文件\n\n本项目按环境拆分配置文件：\n\n- `.env.example`：示例文件，保留全部变量名，用于复制生成本地配置\n- `.env`：本地开发使用的真实配置文件，不建议提交敏感值\n- `.env.docker`：Docker 容器使用的环境变量文件，脚本会在容器启动时读取它\n\n所有配置值通过 `${VAR_NAME:default_value}` 的格式在 YAML 文件中引用。\n\n### 各服务配置说明\n\n各服务的具体环境变量请直接参考对应的 `.env.example`，这里不再重复列出完整配置。\n\n- Spring：`spring/.env.example`、`spring/.env.docker`\n- GoZero：`gozero/app/.env.example`、`gozero/app/.env.docker`\n- NestJS：`nestjs/.env.example`、`nestjs/.env.docker`\n- FastAPI：`fastapi/.env.example`、`fastapi/.env.docker`\n- Gateway：`gateway/.env.example`、`gateway/.env.docker`\n\n使用方式保持一致：\n\n1. 先复制 `.env.example` 为本地 `.env`\n2. 再按实际环境填写真实值\n3. Docker 场景单独维护 `.env.docker`\n\n### 环境变量使用说明\n\n1. **密钥管理**: 所有密钥信息（数据库密码、API KEY、JWT Secret 等）不应该提交到版本控制系统，应该在本地 `.env` 文件中配置\n2. **示例文件**: 新克隆项目后，先复制对应服务的 `.env.example` 为 `.env`，再填写真实值\n3. **Docker 文件**: Docker 运行时读取 `.env.docker`，如果需要修改容器环境变量，请单独维护该文件，不要复用本地 `.env`\n4. **YAML 中的引用格式**: 在各服务的 `application.yaml` 配置文件中，使用以下格式引用环境变量：\n\n   ```yaml\n   # YAML 中的使用示例\n   server:\n     port: ${SERVER_PORT:8080}\n   database:\n     host: ${DB_HOST:localhost}\n     password: ${DB_PASSWORD:default-password}\n   ```\n\n5. **默认值**: 格式 `${VAR_NAME:default_value}` 中，冒号后面是默认值，当环境变量未设置时使用默认值\n6. **加载顺序**: 本地启动时会自动从 `.env` 文件加载环境变量，Docker 启动时会读取 `.env.docker`，然后再解析 YAML 配置文件\n7. **JWT 密钥说明**: 系统环境变量设置的 JWT 密钥至少为 32 位字符串\n\n## Swagger 说明\n\n\u003e 启动时会显示对应的 swagger 地址\n\n### Spring 部分\n\n1. 在 config 包下的 `SwaggerConfig.java`中修改对应 Swagger 信息\n2. 使用 `@Operation(summary = \"spring自己的测试\", description = \"输出欢迎信息\")`设置对应接口\n3. 在 `http://[ip和端口]/swagger-ui/index.html`访问 Swagger 接口\n\n### GoZero 部分\n\n本项目已采用 **API-First** 方式管理 Swagger 文档，所有 API 定义统一存放在 `.api` 文件中，使用 goctl 的内置 Swagger 生成工具自动生成文档。\n\n**使用方式：**\n\n1. 在 `gozero/api` 目录下对应的 `.api` 文件中使用 `@doc` 注释定义 API\n\n   ```api\n   @doc(\n       summary: \"获取用户列表\"\n       description: \"获取所有用户信息\"\n   )\n   get /users returns (UserListResp)\n   ```\n\n2. 在 `gozero/app/main.go` 启动时会自动提供 Swagger UI\n   - Swagger UI: `http://[ip和端口]:8082/swagger/index.html`\n\n3. 每次修改 `.api` 文件后，运行以下命令重新生成 Swagger 文档：\n\n   ```bash\n   # 使用快捷方式\n   ./mix swag\n\n   # 或直接调用脚本\n   cd gozero \u0026\u0026 bash script/swagger/genSwagger.sh\n   ```\n\n4. 生成的 Swagger 文件位于 `gozero/app/docs/` 目录\n5. 目前 Swagger 文档的描述、作者、版本信息和中文分组等相关 Swagger 内容存在问题，使用 `/script/swager/fix.py` 脚本进行修复，修复后会覆盖原来的 Swagger 文件\n\n### NestJS\n\n1. 在 `main.ts`中修改对应 Swagger 信息\n2. 使用 `@ApiOperation({ summary: '获取用户信息', description: '获取用户信息列表' })`设置对应接口\n3. 在 `http://[ip和端口]/api-docs`访问 Swagger 接口\n\n### FastAPI 部分\n\n1. 在 `main.py` 中通过 `FastAPI` 的参数自定义全局 Swagger 信息，例如：\n\n   ```python\n   app = FastAPI(\n       title=\"FastAPI部分的Swagger文档集成\",\n       description=\"这是demo项目的FastAPI部分的Swagger文档集成\",\n       version=\"1.0.0\"\n   )\n   ```\n\n2. 单个接口的描述可以通过路由装饰器的 `description` 参数或函数 docstring 设置，例如：\n\n   ```python\n   @router.get(\n       \"/fastapi\",\n       summary=\"这是接口简介\",\n       description=\"这是接口描述\"\n   )\n   def hello():\n       \"\"\"\n       这是接口的详细说明\n       \"\"\"\n       return {\"msg\": \"hello\"}\n   ```\n\n3. 启动 FastAPI 服务后，访问 `http://[ip和端口]/docs` 查看 Swagger UI，或访问 `http://[ip和端口]/redoc` 查看 ReDoc 文档。\n\n## 项目规范说明\n\n\u003e 这个为当前项目的代码和文件等相关规范，建议遵守\n\n### 项目架构说明\n\n1. Spring 项目采用通用的三层架构，`/controller`为对应接口，`/service`为对应实际逻辑（使用接口+实现形式），`/mapper`为对应数据库操作，并且使用依赖注入进行调用\n2. GoZero 项目采用通用的三层架构，`/handler`为对应接口，`/logic`为对应实际逻辑，`/model`为对应数据库操作，并且使用 `svc`依赖注入进行调用\n3. NestJS 项目采用默认的 module 划分格式，每个 module 有对应的 `xxx.controller.ts`、`xxx.service.ts`、`xxx.module.ts`文件，`/dto`、`/entities`、`/schema` 放置对应的 DTO 类、数据库实体类、Mongoose 实体类，并且使用依赖注入进行调用\n4. FastAPI 项目采用官方推荐的目录结构，在app下实现代码，`api`路由接口，`services`服务逻辑，`crud`为对应数据库操作，`core`放置核心功能模块，并且基于 `Depend`函数和获取实例函数进行依赖注入调用\n\n### 项目文件夹结构说明\n\n1. Spring 项目将三层架构代码放置在 `/api`文件夹下，通用模块放置在 `/common`文件夹下，注解和配置相关放置在 `/core`文件夹下，基础设施相关放置在 `/infra`文件夹下，和实体相关的模块放在 `/entity`下，如 `/dto`、`/vo`、`/po`\n2. GoZero 项目将 `.api`设计文件放置在 `/api`文件夹下，脚本放置在 `/scripts`文件夹下，生成的代码放置在 `/app`文件夹下，`/app` 下采用GoZero的设计方式，`/model`下放置数据库实体和操作，`/common`下放置通用代码模块，`/internal`下放置业务相关的代码模块，`/etc`下放配置文件，`/internal`文件夹下按照 `/handler`、`/logic`等GoZero的设计方式进行划分\n3. NestJS 项目的通用工具放置在 `/common`下，module 相关的工具模块放置在 `/modules`下，接口相关的模块放置在 `/api`下，和系统相关的模块放置在 `/framework`下，如 `filters`、`guards`、`interceptors`等\n4. FastAPI 项目的核心代码放置在 `/app`下，`api`下放置路由接口，`services`下放置服务逻辑，`crud`下放置数据库操作，`core`下放置核心功能模块，`/models`下放置实体相关的模块，`/schemas`下放置 Pydantic 模型\n5. 其他相关的文件夹命名尽可能沿用当前项目的设计\n\n### 项目文件命名说明\n\n1. Spring 项目采用驼峰命名方式，如 `UserCreateDTO.java`\n2. GoZero 项目采用驼峰命名方式，如 `userCreateDTO.go`\n3. NestJS 项目采用点号命名和驼峰命名混合使用的方式，驼峰命名区分模块名，点号区分功能，如 `userCreate.dto.ts`\n4. FastAPI 项目采用驼峰命名方式，如 `userCreateDTO.py`\n\n### 返回格式说明\n\n1. 返回统一使用 `application/json`格式返回，格式如下\n\n   ```json\n   {\n     \"code\": 1,\n     \"data\": Object,\n     \"msg\": \"success\"\n   }\n   ```\n\n- `code`为响应码，1 为成功，0 为失败\n- `data`为实际数据，可以为空，一般是查询返回的结果\n- `msg`为返回信息，成功一般为“success”，失败则为失败原因\n\n2. 一般成功时除查询接口和部分状态管理外，其他接口都是无返回 `data`，即 `data`为 `null`\n3. 失败时 `data`统一为 `null`，错误原因使用 `msg`参数\n4. 无论成功还是失败，HTTP 的状态码均为 200\n\n### 异常处理说明\n\n1. Spring 项目使用全局异常处理类 `GlobalExceptionHandler.java` 进行异常捕获和处理，业务异常统一抛出 `BusinessException` 异常\n2. GoZero 项目使用中间件 `recoveryMiddleware.go` 进行异常捕获和处理，业务异常统一抛出 `BusinessError` 异常\n3. NestJS 项目使用全局异常过滤器 `all-exceptions.filter.ts` 进行异常捕获和处理，业务异常统一抛出 `BusinessException` 异常\n4. FastAPI 项目使用 `exceptionHandlers.py` 下的全局异常处理函数进行异常捕获和处理，业务异常统一抛出 `BusinessException` 异常\n\n### 常量说明\n\n1. Spring 项目使用 `common/utils/Constants.java` 进行常量类管理，包括相关字符串和数字常量\n2. GoZero 项目使用 `common/utils/constants.go` 进行常量管理，包括相关字符串和数字常量\n3. NestJS 项目使用 `common/utils/constants.ts` 进行常量类管理，包括相关字符串和数字常量，当前模板字符串没有抽离常量\n4. FastAPI 项目使用 `core/base/constants.py` 进行常量类管理，包括相关字符串和数字常量，当前模板字符串没有抽离常量\n\n目前常量类均可根据需要进行扩展，尽可能使用常量类进行统一管理，避免硬编码。\n\n### 定时任务说明\n\n1. 统一使用 Cron 表达式的方式进行定时任务管理\n2. 遵循当前项目的定时任务设置方式\n3. 部分定时任务使用 `logic`封装定时任务的实际逻辑，在定时任务主文件调用 `logic`\n\n### 其他说明\n\n1. FastAPI 部分使用 `__init__.py`文件导出对应的函数/类，导入使用的时候以包为导入路径\n2. FastAPI 部分需要在 app 创建时添加的相关组件（如 router、中间件、异常处理器）在 `__init__.py`导出对应列表或者字典，用于 app 创建时遍历添加\n3. FastAPI 部分的 app 创建在 `app.py`的 `create_app`函数实现，lifespan 操作在 `lifespan.py`实现，主函数只进行调用和 `uvicorn`的启动\n4. GoZero 部分的初始化在 `internel/boot` 文件夹创建，main 函数只进行调用，配置相关的初始化在 `svc` 文件夹下初始化执行\n5. NestJS 项目的 app 创建在 `app`目录下的 `createApp`函数实现，main 函数只进行调用，`app`目录下包含 `app.module.ts`的 NestJS 的包初始化\n6. Spring 项目的 Main 类只进行服务的启动，相关配置或初始化行为在 `config`目录下使用 `@Configuration`注解实现\n\n## 项目可用工具说明\n\n### 日志注解/中间件\n\n1. Spring 项目使用 `@ApiLog` 注解 + `ApiLogAspect` 进行请求日志记录，并将日志发送到 RabbitMQ\n\n- 机制: AOP 环绕切面获取请求方法/路径/参数，记录耗时并组装日志消息，最终写入日志并投递队列\n\n2. GoZero 项目使用 `apiLogMiddleware` 中间件记录请求参数、路径、耗时，并发送 API 日志到 RabbitMQ，在 `handler`中使用 `ApplyApiLog` 函数启用日志记录\n\n- 机制: 中间件读取请求上下文与请求体，计算耗时并发送日志消息到队列\n\n3. NestJS 项目使用 `@ApiLog` 装饰器 + `ApiLogInterceptor` 记录日志并发送到消息队列\n\n- 机制: 通过 Reflector 读取装饰器元数据，拦截请求提取参数与耗时，调用 MQ 服务发送日志\n\n1. FastAPI 项目使用 `@log` 装饰器（支持 `ApiLogConfig`）记录请求日志，耗时统计并发送到 RabbitMQ\n\n- 机制: 装饰器从 `Request` 提取方法/路径/参数，统计耗时，必要时包装流式响应并投递日志\n\n### 权限校验注解/中间件\n\n1. Spring 项目使用 `@RequirePermission` 注解 + `PermissionValidationAspect`，支持角色校验、allowSelf、自定义业务类型与参数来源\n\n- 机制: 切面从 `UserContext` 取用户信息，解析路径/请求体参数，按业务类型与参数来源判断权限\n\n2. GoZero 项目暂无通用权限注解，中间件 `InjectUserContext` 仅负责注入用户信息，权限校验主要在业务层处理\n\n- 机制: 中间件只把 `X-User-Id`/`X-Username` 注入到上下文，具体权限由 service/handler 自行校验\n\n3. NestJS 项目使用 `@RequireAdmin` 装饰器 + `RequireAdminGuard` 进行管理员权限校验\n\n- 机制: Guard 读取装饰器元数据与 CLS 用户信息，调用用户服务判断是否管理员\n\n4. FastAPI 项目使用 `@require_admin` 装饰器进行管理员权限校验\n\n- 机制: 装饰器读取当前用户 ID 并查询用户角色，不满足条件抛出业务异常\n\n### 内部服务令牌注解/中间件\n\n1. Spring 项目使用 `@RequireInternalToken` 注解 + `InternalTokenAspect` 校验 `X-Internal-Token`，并通过 Feign `DefaultHeaderInterceptor` 自动注入内部令牌\n\n- 机制: Feign 拦截器生成内部 JWT 并写入请求头，切面解析并校验令牌及服务名称\n\n2. GoZero 项目使用 `InternalTokenMiddleware` 校验内部令牌，支持验证指定服务名称\n\n- 机制: 中间件从请求头读取 JWT，校验签名/过期/服务名，失败直接中断请求\n\n3. NestJS 项目使用 `@RequireInternalToken` 装饰器 + `InternalTokenGuard` 校验内部服务令牌\n\n- 机制: Guard 从请求头提取 JWT，验证并检查指定服务名匹配\n\n4. FastAPI 项目使用 `@requireInternalToken` 装饰器校验内部服务令牌，并支持指定服务名称\n\n- 机制: 装饰器读取 `X-Internal-Token`，校验并将 claims 写入 `request.state`\n\n### 服务间调用工具\n\n1. Spring 项目使用 Feign 客户端 `FastAPIClient`/`GoZeroClient`/`NestjsClient` 调用其他服务，`DefaultHeaderInterceptor` 自动注入用户信息与内部令牌\n\n- 机制: Feign 统一注入 `X-User-Id`/`X-Username` 与内部 JWT，实现服务间安全调用\n\n2. GoZero 项目使用 `ServiceDiscovery.CallService`（Nacos 服务发现 + 负载均衡），自动注入用户信息与内部令牌\n\n- 机制: 通过 Nacos 获取实例并轮询负载均衡，构建请求头后发起 HTTP 调用\n\n3. NestJS 项目使用 `NacosService.call`（Nacos 服务发现 + axios），自动注入用户信息与内部令牌\n\n- 机制: Nacos 发现实例，自动拼装请求头并用 axios 请求下游服务\n\n4. FastAPI 项目使用 `call_remote_service`（Nacos 服务发现 + requests），自动注入用户信息与内部令牌\n\n- 机制: 从 Nacos 获取服务实例，合并默认请求头后用 requests 发起调用\n\n## 其他说明\n\n### FastAPI Agent 工具说明\n\nFastAPI 部分提供了基于 LangChain 的 AI Agent 工具，AI 模型可以通过这些工具进行数据查询和分析。\n\n#### 1.SQL 数据库工具\n\n通过 MySQL 数据库进行数据查询和分析：\n\n| 工具名称            | 功能          | 参数            | 说明                                                                             |\n| ------------------- | ------------- | --------------- | -------------------------------------------------------------------------------- |\n| `get_table_schema`  | 获取表结构    | 表名(可选)      | 返回表的详细结构信息，包括列名、类型、主键、索引等；不提供表名则返回所有表的列表 |\n| `execute_sql_query` | 执行 SQL 查询 | SQL SELECT 语句 | 仅支持 SELECT 查询，自动进行用户隔离过滤，返回最多 500 行数据                    |\n\n#### 2.RAG 向量搜索工具\n\n基于 PostgreSQL + Qwen 嵌入模型的文章向量搜索：\n\n| 工具名称          | 功能         | 参数         | 说明                                                          |\n| ----------------- | ------------ | ------------ | ------------------------------------------------------------- |\n| `search_articles` | 向量语义搜索 | 问题或关键词 | 基于语义相似度搜索相关文章，返回相似度最高的 N 篇文章内容片段 |\n\n#### 3.MongoDB 日志查询工具\n\n查询系统日志和 API 调用记录：\n\n| 工具名称                   | 功能     | 参数              | 说明                                          |\n| -------------------------- | -------- | ----------------- | --------------------------------------------- |\n| `list_mongodb_collections` | 列出集合 | 无                | 获取 MongoDB 中所有的 collection 及其基本信息 |\n| `query_mongodb`            | 通用查询 | JSON 格式查询参数 | 查询任意 collection，支持条件过滤和结果限制   |\n\n**MongoDB 查询参数格式示例：**\n\n```json\n{\n  \"collection_name\": \"api_logs\",\n  \"filter_dict\": { \"user_id\": 122, \"status\": { \"$gte\": 400 } },\n  \"limit\": 20\n}\n```\n\n#### 4.其他工具\n\n- **意图路由工具 (intentRouter.py)**: 用于自动识别用户意图并路由到不同的处理模块\n- **用户权限管理 (userPermissionManager.py)**: 管理和校验用户权限，实现细粒度访问控制\n\n### 词云图说明\n\n1. 词云图的字体应进行配置对应字体的路径\n\n### 下载说明\n\n1. Word 下载文件的模板路径在 NestJS 部分 yaml 配置文件中配置，使用 `${字段名}`进行模板书写，目前提供如下的示例\n2. 内容示例\n\n   ```word\n   ${title}\n\n   ${tags}\n\n   ${content}\n   ```\n\n3. PDF 下载需要使用下面指令安装 `puppeteer`的 Chrome 浏览器\n\n   ```bash\n   npx puppeteer browsers install chrome\n   ```\n\n4. 当前 Word 下载只支持文章内容为纯文本，无法显示 Markdown 格式\n\n### AI 说明\n\n1. Gemini 服务目前使用第三方平台 [Close AI](https://platform.closeai-asia.com/dashboard) ，根据说明文档进行配置\n2. FastAPI 模块的豆包服务、 Gemini 服务和通义千问服务的 api_key 应写在 `.env`中\n\n### 用户聊天相关说明\n\n1. GoZero 部分的用户聊天相关模块的用户 id 都是字符串，包括数据库存储，请求参数和返回参数\n\n### AI 用户说明\n\n1. AI 服务目前只有三种，对应数据库 `user`表里面 `role`为 `ai`的用户，并且代码目前写死用户 id 为 1001/1002/1003，系统创建用户表时会自动创建，有需要可进行更改。\n\n### 邮箱说明\n\n1. Spring 部分的邮箱登录使用 QQ 邮箱配置发送，需单独配置 QQ 邮箱授权码。\n\n### Fresh 热启动工具说明\n\n1. GoZero 服务若使用 `fresh`修改热启动工具，可以在配置对应配置文件用于修改编译结果产生位置，示例如下\n\n   ```bash\n   # Fresh 热启动工具配置文件\n   # 将编译文件输出到系统临时目录，不污染项目目录\n\n   root=.\n   # 输出到系统临时目录 (/tmp) 而不是项目目录\n   tmp_path=/tmp/fresh-runner\n   build_name=runner-build\n   build_path=/tmp/fresh-runner\n   build_delay=1000\n   ignore_folder=assets,tmp,vendor,frontend/node_modules,logs,docs\n   ignore_file=.DS_Store,.gitignore\n   watch_path=.\n   watch_ext=.go\n   verbose=false\n   ```\n\n### 搜索算法公式说明\n\n1. GoZero 服务基于 ElasticSearch 实现的文章搜索采用综合评分算法，综合考虑多个维度的因素。\n2. 综合评分公式\n\n$$\n\\text{Score} = w_1 \\cdot S_{es} + w_2 \\cdot S_{ai} + w_3 \\cdot S_{user} + w_4 \\cdot S_{views} + w_5 \\cdot S_{likes} + w_6 \\cdot S_{collects} + w_7 \\cdot S_{follow} + w_8 \\cdot S_{recency}\n$$\n\n3. 其中：\n\n- $S_{es} = \\frac{1}{1 + e^{-x}}$（Sigmoid 归一化的 ElasticSearch 相关性分数，0-1 范围）\n- $S_{ai} = \\frac{\\text{AI评分}}{10.0}$（0-1 范围，AI 评分范围为 0-10）\n- $S_{user} = \\frac{\\text{用户评分}}{10.0}$（0-1 范围，用户评分范围为 0-10）\n- $S_{views} = \\min\\left(\\frac{\\text{阅读量}}{\\text{maxViewsNormalized}}, 1.0\\right)$（阅读量归一化，0-1 范围）\n- $S_{likes} = \\min\\left(\\frac{\\text{点赞量}}{\\text{maxLikesNormalized}}, 1.0\\right)$（点赞量归一化，0-1 范围）\n- $S_{collects} = \\min\\left(\\frac{\\text{收藏量}}{\\text{maxCollectsNormalized}}, 1.0\\right)$（收藏量归一化，0-1 范围）\n- $S_{follow} = \\min\\left(\\frac{\\text{作者关注数}}{\\text{maxFollowsNormalized}}, 1.0\\right)$（作者粉丝数归一化，0-1 范围）\n- $S_{recency}$：文章新鲜度分数（基于创建时间）\n\n4. 新鲜度计算公式\n\n- 文章新鲜度采用高斯衰减函数，使时间离当前越近的文章得分越高：\n\n$$\nS_{\\text{recency}} = e^{-\\frac{(\\Delta t)^2}{2\\sigma^2}}\n$$\n\n- 其中：\n  - $\\Delta t$：文章创建时间与当前时间的差值（单位：天）\n  - $\\sigma$：时间衰减周期（默认 30 天）\n\n- 高斯衰减函数具有以下特性：\n  - 当 $\\Delta t = 0$（刚发布）时，$S_{\\text{recency}} = 1.0$（新鲜度最高）\n  - 当 $\\Delta t = 30$ 天时，$S_{\\text{recency}} \\approx 0.606$（衰减至约 60.6%）\n  - 当 $\\Delta t = 60$ 天时，$S_{\\text{recency}} \\approx 0.135$（衰减至约 13.5%）\n\n- 权重配置说明\n\n  | 默认权重分配（可在 GoZero 部分的 `.env` 中配置）： | 因素     | 权重                                          | 说明 |\n  | -------------------------------------------------- | -------- | --------------------------------------------- | ---- |\n  | ES 基础分数                                        | 0.25     | 关键词匹配的基础相关性（通过 Sigmoid 归一化） |      |\n  | AI 评分                                            | 0.15     | 系统 AI 模型的内容质量评估（0-10 范围）       |      |\n  | 用户评分                                           | 0.10     | 用户对文章的综合评价（0-10 范围）             |      |\n  | 阅读量                                             | 0.08     | 文章的浏览热度                                |      |\n  | 点赞量                                             | 0.08     | 用户的认可度                                  |      |\n  | 收藏量                                             | 0.08     | 用户的收藏价值指数                            |      |\n  | 作者关注数                                         | 0.04     | 作者的影响力                                  |      |\n  | **文章新鲜度**                                     | **0.22** | **核心权重，近期发布的内容获得更高排名**      |      |\n  - 权重总和为 1.0，确保评分结果的可比性和公平性。\n\n## 许可证\n\n本项目采用 [MIT 许可证](./LICENSE) 进行开源。\n\nMIT 许可证允许：\n\n- 自由使用、修改和分发\n- 商业和个人用途\n- 专利使用\n\n详见 [LICENSE](./LICENSE) 文件\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongch666%2Fmix-web-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhongch666%2Fmix-web-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongch666%2Fmix-web-demo/lists"}