# bytech-cloud
**Repository Path**: ningbo-boyu/bytech-cloud
## Basic Information
- **Project Name**: bytech-cloud
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 8
- **Forks**: 3
- **Created**: 2026-06-23
- **Last Updated**: 2026-10-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# javatech-cloud
基于 Spring Cloud 微服务架构的 **SaaS 多租户平台**，支持微服务 / 单体一键切换部署。
## 演示图
| | |
|---|---|
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  |  |
|  | |
## 核心功能
| 功能 | 说明 |
|------|------|
| **双系统登录切换** | 平台管理员 + 租户用户两套身份体系，前端任意切换互不冲突 |
| **多租户数据隔离** | 基于 MySQL Schema（`USE database`）的轻量级隔离，每个租户独立库 |
| **微服务/单体双模式** | `monolith` Profile 一键聚合，单体模式下 Feign 接口零网络开销 |
| **RBAC 权限模型** | 平台/租户两套 RBAC 体系，`@PreAuth` 方法级权限 + 前端路由守卫 |
| **操作审计日志** | 等保三级合规的 `@OperLog` + `@DataChangeLog` + HTTP 访问日志 |
| **文件服务** | 文件上传/批量上传/下载/预览/缩略图 / 本地 + 多云存储适配（OSS/COS/MinIO/七牛/OBS/S3） |
| **系统监控** | 服务监控（SBA：CPU/内存/JVM/GC + 动态日志级别）、Redis 监控、在线用户管理 |
| **IP 黑名单** | 支持 API / Gateway 两级拦截 |
| **代码生成器** | MyBatis-Plus 代码生成，一键生成 Controller/Service/Mapper/Entity |
| **AI 智能对话** | 8 大平台多渠道路由（OpenAI/DeepSeek/智谱GLM/文心一言/腾讯混元/Kimi/通义千问/Ollama）+ 渠道管理 + 对话历史 |
| **定时任务** | 基于 XXL-JOB 的分布式任务调度：任务管理 / 执行日志 / 微服务分布式 + 单体双模适配 |
| **登录验证码** | 统一可插拔验证码体系：图片 / 短信 / TOTP 三类型可配置启停，策略模式 + SPI 解耦，前后端联动 |
| **WAF 应用防火墙** | 自研应用内 WAF：双模（网关 / Servlet）检测、SQL 注入 / XSS / 路径穿越 / 命令注入 / 扫描器指纹检测、灰度上线、攻击日志落库、非业务 URL / 可疑参数 / 登录失败轻量观测 |
## 技术选型
| 类别 | 技术 | 版本 |
|------|------|------|
| 基础框架 | Spring Boot + Spring Cloud + Spring Cloud Alibaba | 3.2.5 / 2023.0.1 |
| 注册/配置 | Nacos | 2.3.2 |
| 网关 | Spring Cloud Gateway (WebFlux) | 4.1.x |
| 数据库 | MySQL | 8.0 |
| 连接池 | Druid | 1.2.20 |
| ORM | MyBatis-Plus + dynamic-datasource | 3.5.5 / 4.2.0 |
| 安全认证 | Sa-Token（双 StpLogic）+ JWT | 1.37.0 |
| 远程调用 | OpenFeign + LoadBalancer | 4.1.1 |
| 缓存 | Redis + Redisson | 7.x |
| API 文档 | Knife4j (OpenAPI 3.0) | 4.4.0 |
| 对象转换 | MapStruct | 1.5.5 |
| 工具库 | Hutool | 5.8.24 |
| IP 定位 | ip2region（离线） | 3.3.7 |
| AI 对话 | LangChain4j | 0.35.x |
| 定时任务 | XXL-JOB | 2.4.0 |
| Java | JDK 17 | - |
## 模块结构
```
javatech-cloud
├── bytech-common 公共模块聚合
│ ├── bytech-common-core 核心：R、异常、常量、TenantContextHolder
│ ├── bytech-common-security-core 安全核心：白名单、IP 黑名单、WAF 检测核心（无 Web 依赖）
│ ├── bytech-common-security 安全：@PreAuth、LoginUser、Sa-Token 双 StpLogic
│ ├── bytech-common-log 日志：@OperLog / @DataChangeLog / 访问日志
│ ├── bytech-common-web Web：全局异常处理、Jackson、Knife4j
│ ├── bytech-common-redis Redis：序列化、缓存、分布式锁
│ ├── bytech-common-mybatis MyBatis：分页、自动填充、动态数据源、Druid
│ └── bytech-common-tenant 多租户：Schema 拦截器、Header 提取、Feign 透传
├── bytech-feign-api Feign API 聚合
│ ├── bytech-feign-api-system 系统服务 API
│ ├── bytech-feign-api-platform 平台服务 API
│ ├── bytech-feign-api-file 文件服务 API
│ └── bytech-feign-api-ai AI 服务 API（对话/渠道远程调用）
├── bytech-gateway Spring Cloud Gateway 网关
├── bytech-auth 认证服务（登录/登出/权限加载）
├── bytech-monitor 系统监控（服务监控 SBA / Redis 监控 / 在线用户）
├── bytech-modules 业务模块聚合
│ ├── bytech-system 租户系统（用户/角色/菜单/部门/字典/日志/配置）
│ ├── bytech-platform 平台管理（租户CRUD/套餐/平台RBAC）
│ ├── bytech-file 文件服务（上传/下载/预览/多云存储适配）
│ ├── bytech-ai AI 智能（多渠道路由对话 / 渠道管理 / 对话历史）
│ ├── bytech-job 定时任务（XXL-JOB 分布式调度 / 任务管理 / 执行日志）
│ └── bytech-waf WAF（攻击日志消费 / 管理后台规划）
└── bytech-boot 单体启动聚合模块
```
## 双系统登录切换
平台管理员和租户用户拥有**完全独立的身份体系**，共享同一前端、同时在线、自由切换。
```
┌─────────────────────────────────────────────────────┐
│ 平台管理员 (loginType="platform") │
│ 路径: /platform/* StpLogic: platformStpLogic │
│ Token Redis Key: platform:token:xxx │
│ 数据库: bytech_platform （全局唯一） │
├─────────────────────────────────────────────────────┤
│ 租户用户 (loginType="auth") │
│ 路径: /system/* StpLogic: stpLogic (主) │
│ Token Redis Key: auth:token:xxx │
│ 数据库: bytech_system_{tenantCode}（每个租户独立库） │
└─────────────────────────────────────────────────────┘
```
- 两套 `StpLogic` 共享同一个 Redis 连接，通过不同 `loginType` 实现 Key 隔离，**可同时在线互不覆盖**
- 前端双 Token 并存于 `localStorage`，`currentLoginType` 存于 `sessionStorage`（多 Tab 独立）
- 退出时自动切换到另一已登录身份
> 详细文档：[docs/双系统同时登录机制.md](docs/双系统同时登录机制.md)
## 多租户数据隔离
采用 **Schema 级隔离**（每个租户独立 MySQL 库），轻量且高效。
```
HTTP 请求 (Authorization: Bearer {token})
│
├─ Gateway AuthFilter
│ └─ 从 Redis TokenSession 读取 LoginUser → tenantCode
│ └─ 写入可信 Tenant-Code Header（先清除外部伪造头）
│
├─ TenantHeaderInterceptor（Servlet Filter）
│ └─ Header → TenantContextHolder (TransmittableThreadLocal)
│
└─ TenantSchemaInterceptor（MyBatis Plugin）
└─ SQL 执行前 USE bytech_system_{tenantCode}
└─ 无 tenantCode → 降级 USE bytech_system
```
| 组件 | 路径 | 功能 |
|------|------|------|
| `TenantContextHolder` | `bytech-common-core/.../holder/` | TransmittableThreadLocal 线程安全传递 |
| `TenantHeaderInterceptor` | `bytech-common-tenant/.../interceptor/` | 从 Header 提取并设置上下文 |
| `TenantSchemaInterceptor` | `bytech-common-tenant/.../interceptor/` | MyBatis Plugin，SQL 前动态 USE |
| `TenantFeignInterceptor` | `bytech-common-tenant/.../interceptor/` | Feign 调用时透传租户信息 |
| `TenantCodeResolver` | `bytech-common-security/.../utils/` | 从 Token 或 Session 解析 tenantCode |
**数据源设计**：
- `tenant` 数据源（primary）：共享连接池，`USE` 动态切换，零额外开销
- `platform` 数据源：`@DS("platform")` 注解切换，固定连接 `bytech_platform`
**可拔插**：不引入 `bytech-common-tenant` 时，多租户完全不激活。
## 微服务 / 单体双模式
通过 `monolith` Profile 一键切换，单体模式直接注入 Controller Bean 替代 Feign HTTP 调用。
| 模式 | Profile | Nacos | Feign | 启动方式 |
|------|---------|-------|-------|---------|
| **微服务** | `dev`/`prod` | ✅ 启用 | ✅ HTTP 代理 | 分别启动各服务 |
| **单体** | `monolith` | ❌ 禁用 | ❌ 本地注入 | 启动 bytech-boot 即可 |
```bash
# 单体模式（一键启动）
mvn clean package -pl bytech-boot -DskipTests
java -jar bytech-boot/target/bytech-boot-exec.jar --spring.profiles.active=monolith
# 微服务模式（需先启动 Nacos）
# 依次启动 gateway → auth → system → platform → file → ai → job → monitor
```
**单体模式核心设计**：
- `bytech-boot` 聚合所有业务模块，`@ComponentScan("com.bytech")` 全量扫描
- `SecurityConfig`（`@Profile("monolith")`）：Servlet 拦截器链（安全配置不依赖 Gateway）
- Controller `implements FeignClient` 接口，单体模式下 `@Autowired` 直接注入本地 Bean，零网络开销
> 详细文档：[docs/API_CALLING_CONVENTION.md](docs/API_CALLING_CONVENTION.md)
## 审计日志体系
等保三级合规的完整审计方案，三种维度覆盖：
| 类型 | 注解/采集 | 存储表 | 说明 |
|------|-----------|--------|------|
| **操作日志** | `@OperLog` | `sys_oper_log` / `platform_oper_log` | 记录增删改查等业务操作 |
| **数据变更** | `@DataChangeLog` | `sys_data_change_log` | 新旧值 diff 对比 |
| **访问日志** | 全局拦截器自动采集 | `sys_access_log` / `platform_access_log` | HTTP 请求全量审计 |
**访问日志架构**：
```
单体模式: AccessLogInterceptor (Servlet) → AsyncLogService → Feign → Controller → DB
微服务: AccessLogGatewayFilter (Gateway) → WebClient POST → Controller → DB
```
日志表通过数据库触发器禁止 UPDATE/DELETE，等保合规不可篡改。
## 系统监控
`bytech-monitor` 模块提供服务监控 / Redis 监控 / 在线用户三大能力，微服务与单体双模式通用。
| 能力 | 说明 |
|------|------|
| **服务监控** | 基于 Spring Boot Admin，聚合各服务 CPU / 内存 / JVM / GC 指标，支持实例详情、健康检查、动态调整日志级别；微服务 / 单体双模 |
| **Redis 监控** | 直连 Redis，实时展示连接数、命中率、内存使用量、慢日志、客户端、命令统计与性能趋势 |
| **在线用户** | 实时查看在线用户列表，支持强制下线 |
**双模式实现**：`/monitor/instance/*` 统一入口，通过 `ServerMonitorService` 接口按 `@Profile` 切换——微服务模式（`!monolith`）由 SBA 聚合多实例，单体模式（`monolith`）直读本机 Actuator；前端零改动。
> 详细文档：[docs/system-monitoring.md](docs/system-monitoring.md)
## WAF（Web 应用防火墙）
自研的**应用内 WAF**，采用「Spring Cloud Gateway（WebFlux `GlobalFilter`）+ Boot（Servlet `Filter`）双模」架构，检测核心下沉到 `bytech-common-security-core` **双端复用**；覆盖 SQL 注入 / XSS / 路径穿越 / 命令注入 / SSRF / 扫描器指纹 / 协议合规等规则组，支持**灰度上线（仅观察）**、**四级开关**、**故障隔离（fail-open）**与**轻量安全观测**。
> 完整设计（架构、序列图、规则清单、Redis 约定、阶段规划）：[docs/waf-design.md](docs/waf-design.md)
### 核心能力
| 能力 | 说明 |
|------|------|
| **双模检测架构** | 网关侧 `WafGatewayFilter`（`order = -300`）与单体侧 `WafServletFilter` 共用 `bytech-common-security-core` 检测核心，规则 / 阈值 / 开关同一份配置，零重复代码 |
| **规则组** | `SQLI`（SQL 注入）/ `XSS` / `PATH`（路径穿越）/ `CMD`（命令注入、SSRF）/ `SCANNER`（扫描器指纹，如 `curl`、`sqlmap`）/ `PROTO`（协议合规） |
| **灰度上线** | `action: OBSERVE`（仅记录不拦截）→ 观察期无业务误杀 → `BLOCK`（拦截），上线风险可控 |
| **四级开关** | 总开关 `waf.enabled` → 装配开关 `waf.servlet-filter.enabled` → 行为开关（observe-only）→ 规则组开关，支持 Nacos 热更新 |
| **故障隔离（fail-open）** | 过滤器 / 规则异常一律放行并告警，WAF 自身故障不影响业务；Redis 不可用时降级为本地不落库 |
| **攻击日志落库** | 命中事件经 Redis 队列 `waf:log:queue` → `WafAttackLogConsumer` → `waf_attack_log`，与轻量观测共用同一表与看板 |
| **轻量安全观测（已落地）** | 非业务 URL（`[NON-BUSINESS-URL]`）、可疑参数（`[SUSPECT-PARAM]`）、登录失败（`[AUTH-FAIL]`）经 `ObserveAttackLogPublisher` 落库 `waf_attack_log`，以 `rule_group`（`OBSERVE` / `AUTH-FAIL`）与真实攻击区分，零新表 |
| **动态频控 / 封禁（P1）** | 按 IP / UA / 会话对命中做计数与滑动窗口限速，支持临时封禁（`WafRateLimiter` 接口已定义，实施中） |
| **管理后台 / 攻击地图（P2）** | 安全总览、攻击日志查询、封禁管理、自定义规则、实时攻击地图、风险报表（规划中） |
### 双模架构
```
请求
├─ 微服务: Gateway → WafGatewayFilter (WebFlux, order=-300) → AuthFilter → 路由
└─ 单体: Servlet 容器 → WafServletFilter → 业务 Controller
↓ 共用
bytech-common-security-core: WafDetector（规则匹配）+ WafRuleProvider（规则加载 / 热更新）
↓ 命中
waf:log:queue（Redis List）← WafRedisSyncLogSink
↓ 消费
WafAttackLogConsumer（bytech-waf 模块） → waf_attack_log（bytech_system 库）
```
### 轻量观测落库（已落地）
四类安全事件统一进入 `waf_attack_log`，通过 `rule_group` 与真实攻击区分：
| rule_group | rule_id | 触发点 | severity |
|------------|---------|--------|----------|
| `OBSERVE` | `OBSERVE-URL` | 404 非业务 URL（`GlobalExceptionHandler.handleNoResourceFound`） | 2 |
| `OBSERVE` | `OBSERVE-PARAM` | 真实接口的可疑参数（`SecurityObserveFilter`，只读、只记不拦） | 2 |
| `AUTH-FAIL` | `LOGIN-BAD-CRED` / `LOGIN-DISABLED` / `LOGIN-LOCKED` / `LOGIN-TENANT` | 登录失败（`AuthController`，账户锁定 = 3，其余 = 2） | 2 / 3 |
### 实施阶段
- **P0（已落地）**：检测核心 + 双模过滤器 + 规则集 + 四级开关 + 灰度上线 + 故障隔离 + 轻量观测落库；
- **P1（实施中）**：攻击日志落库（`WafAttackLogConsumer` 已实现）、动态频控 / 封禁；
- **P2（规划）**：管理后台、实时攻击地图、风险报表、自定义规则 UI。
### 关键配置（Nacos / `application.yml`）
| 配置 | 默认值 | 说明 |
|------|--------|------|
| `waf.enabled` | `true` | 总开关 |
| `waf.servlet-filter.enabled` | 微服务 `false` / 单体 `true` | 单体侧装配开关（网关侧始终生效） |
| `waf.rules.default.action` | `OBSERVE` | 默认行为：`OBSERVE`（仅观察）/ `BLOCK`（拦截） |
| `waf.observe.exclude-ips` / `waf.observe.exclude-paths` | 回环、`/actuator/health` | 轻量观测排除项（本地 / 健康检查流量不记录） |
## 路线图 (TODO)
以下模块中的**已完成功能**（打勾）可直接使用；其余为下一阶段计划。
### 系统监控
| 功能 | 状态 | 说明 |
|------|------|------|
| ✅ 服务监控 | **已完成** | Spring Boot Admin，查看各服务 CPU/内存/JVM/GC 指标，支持实例详情、健康检查、动态日志级别；微服务 / 单体双模 |
| ✅ Redis 监控 | **已完成** | Redis 连接数、命中率、内存使用量、慢日志、客户端、命令统计、性能趋势等实时监控 |
| ✅ 在线用户 | **已完成** | 实时查看在线用户列表，支持强退 |
| ✅ 定时任务 | **已完成** | 基于 XXL-JOB 的分布式任务调度：任务管理 / 执行日志 / 微服务分布式 + 单体双模适配 |
### 文件服务
| 功能 | 状态 | 说明 |
|------|------|------|
| ✅ 本地 / 多云存储适配 | **已完成** | 本地磁盘 + 阿里云 OSS + 腾讯云 COS + MinIO + 七牛 + 华为 OBS + S3，配置切换 |
| ✅ 文件上传 / 下载 / 预览 | **已完成** | 单文件上传、批量上传、下载、图片预览、缩略图、访问地址解析 |
| 断点续传 | 待实现 | 大文件分片上传，支持暂停/恢复 |
| 文件水印 | 待实现 | 图片/PDF 动态水印，防盗溯源 |
### 开发工具
| 功能 | 状态 | 说明 |
|------|------|------|
| ✅ 开放接口 | **已完成** | Swagger / Knife4j 在线调试，按服务自动分组生成 API 文档 |
| 代码生成 | 待实现 | 支持在线生成 Controller / Service / Mapper / Entity / Vue 页面 |
| 在线表单 | 待实现 | 可视化拖拽表单设计器，动态生成 CRUD 页面 |
| 流程控制 | 待实现 | 集成 Flowable 工作流引擎，支持可视化流程设计 |
### 协议管理
Web 端与 Uniapp 端相关协议（用户协议、隐私政策等）的统一管理与双端展示。本期范围：**协议内容管理 + 双端展示**；版本管理、用户同意留痕、强制更新提示等配套能力纳入后续迭代。
| 功能 | 状态 | 说明 |
|------|------|------|
| 协议类型管理 | 待实现 | 内置预置常用协议类型（`agreement_type`），支持类型扩展与自定义 |
| 协议内容管理 | 待实现 | 富文本编辑协议内容，web 后台维护、双端只读展示 |
| 协议类型内置种子 | 待实现 | 预置：用户服务协议、隐私政策、儿童隐私保护指引、Cookie 政策、第三方共享清单、会员/付费服务协议、账号注销协议、免责声明、开发者/开放平台协议、未成年人保护 |
| Web 后台管理 | 待实现 | bytech-ui 动态菜单新增"协议管理"页，协议类型 + 内容的 CRUD |
| Uniapp 端展示 | 待实现 | 注册 / 登录勾选协议链接、设置-关于内协议列表，打开协议详情页（富文本渲染） |
| 多端内容一致 | 待实现 | Web 与 Uniapp 共用同一协议数据源（bytech-system 模块 `system/agreement` 接口） |
**落地位置**：后端 `bytech-system` 模块新增协议 Controller/Service/Mapper/Entity（复用通知公告的富文本 + `@PreAuth` 权限模式），web 端加动态菜单后台管理页，uniapp 端在注册/登录/设置-关于接入协议展示页。
### AI 功能
#### ✅ 已完成：AI 智能对话模块
| 功能 | 说明 |
|------|------|
| AI 对话 | ChatGPT 风格对话界面，支持多轮对话、对话历史切换/删除、渠道/模型选择 |
| AI 渠道管理 | 8 大平台渠道 CRUD：OpenAI、DeepSeek、智谱GLM、文心一言、腾讯混元、Kimi、通义千问、Ollama；API Key AES 加密存储 |
| 多渠道路由 | 按 `channelCode` 或优先级自动路由到启用渠道，模型实例按 `渠道:模型` 缓存复用 |
| 对话历史 | 按当前用户隔离，对话 + 消息持久化到 `ai_conversation` / `ai_message`，支持继续历史对话（带上下文） |
| Feign 远程调用 | `bytech-feign-api-ai` 暴露 `AiChatFeignClient`，其他服务可远程调用对话能力 |
#### 规划中
| 功能 | 说明 |
|------|------|
| 智能助手 | 接入大语言模型，自然语言查询数据、生成报表 |
| 代码审查 | AI 辅助代码 Review，自动检测规范和安全问题 |
| 智能日志分析 | 异常日志自动聚类、告警、给出修复建议 |
| 合规检查 | AI 自动审计操作日志，识别异常行为 |
| 流式输出 | 对话改为 SSE 流式打字机效果 |
### 安全增强
登录验证码采用**统一可插拔架构**（`CaptchaManager` 调度 + `CaptchaProvider` 策略 + `CaptchaStorage`/`CaptchaConfigReader`/`SmsSender`/`TotpSecretResolver` SPI 解耦），所有类型集中配置于 `sys_config`，**默认全部关闭**，可任意组合、动态切换；前端按 `/auth/captcha/config` 返回的开关动态展示与拼装参数。
#### 三类验证码开关与参数（`sys_config`）
| 类型 | 开关 key | 说明 | 关键参数（默认值） |
|------|----------|------|-------------------|
| 图片 image | `security.captcha.image.enabled` | AWT 自绘（纯数字 / 数字计算 / 中文数字计算），返回 `key` + `imageBase64`，零额外依赖 | 过期 `image.expire`（120s）、类型 `image.type`（number/char） |
| 短信 sms | `security.captcha.sms.enabled` | 经 `SmsGateway`（阿里云/腾讯云，配置切换）下发 6 位码 | 有效期 `sms.expire`（300s）、发送间隔 `sms.interval`（60s） |
| 动态码 totp | `security.captcha.totp.enabled` | RFC 6238（自实现 HMAC-SHA1 + Base32，无三方库依赖），兼容 Google Authenticator | 30s 窗口，前后各 1 个周期容错 |
#### 校验时机与契约（登录 `LoginDTO`）
- 登录参数带 `captchaType`（`image`/`sms`/`totp`）、`captchaKey`、`captcha`；`captchaKey` 取值：图片=`uuid`、短信/动态码=登录账号（后端按账号解析绑定手机号 / TOTP 密钥）。
- **短信**：开启即强制校验，收信号码严格以用户表 `phone` 字段为准（账号解析，前端不手填手机号）。
- **TOTP**：仅当用户已绑定时才要求校验（防止已绑定用户绕过），未绑定则直接放行；返回 `totpBound`（`true` 已绑定已验证 / `false` 未绑定 / `null` 未开启）供前端引导绑定。
- **图片**：仅前端选择该类型时校验；`captchaType` 为空则跳过验证码校验。
#### 其它安全能力
| 功能 | 说明 |
|------|------|
| IP 频控 / 防重放 | 图片验证码 IP 维度频控 + 一次性消费，短信验证码发送间隔 / 有效期可配置，防刷防轰炸 |
| TOTP 密钥安全 | 密钥 AES 加密存储，绑定后登录二次验证 |
| IP 黑白名单管理 | 可视化配置 IP 白名单 / 黑名单，按模块 / 接口级别生效，支持 CIDR 网段、定时放行 / 封禁 |
| 登录失败锁定 | 连续失败达 `MAX_FAIL_COUNT=5` 次锁定账户（`AuthController` 的 `ACCOUNT_LOCKED` 逻辑） |
| 登录审计日志 | IP、UA、地理位置、端口、失败原因、失败次数、登录类型、租户编码，通过 Feign 异步落 `sys_login_log` / `pf_login_log` |
| 双 Token 隔离 | 平台管理员与租户用户 Token 采用双 `StpLogic`（`loginType` = `platform` / `auth`），Redis Key 前缀隔离，二者可同时在线 |
> 详细设计与实现原理（架构图、时序、Redis Key 约定）：[docs/captcha-design.md](docs/captcha-design.md)
### IP 地理位置
集成 ip2region 3.x 离线数据库，无需联网，微秒级解析。
**开启方式**：将 `ip2region_v4.xdb` / `ip2region_v6.xdb` 放入 `bytech-common/bytech-common-core/src/main/resources/ipdb/`
下载地址：[ip2region data](https://github.com/lionsoul2014/ip2region/tree/master/data)
## Docker 部署
项目提供 `docker-bytech/` 目录，内置 Docker Compose 编排文件，支持**微服务**与**单体**两种部署模式，开箱即用。
### 目录结构
```
docker-bytech/
├── docker-compose.yml # 编排文件（按 profile 区分微服务 / 单体）
├── .env / .env.example # 环境变量（密码、端口、JVM 内存等）
├── copy.sh # 一键复制 jar / SQL / 前端 dist 到部署目录
├── bytech-cloud/ # 各服务构建上下文（Dockerfile + jar）
│ ├── gateway/ auth/ platform/ system/ file/ ai/ job/ monitor/ boot/
├── mysql/ redis/ nacos/ # 中间件配置文件与初始化脚本
└── nginx/ # 前端静态资源 + 反向代理（微服务模式）
```
### 部署步骤
```bash
# 1. 项目根目录打包所有模块
mvn clean package -DskipTests
# 2. 进入 docker 目录，复制产物
cd docker-bytech
cp .env.example .env # 修改密码等变量
./copy.sh # 复制 jar / SQL / 前端 dist
# 3. 构建镜像
docker compose build
# 4. 启动（二选一）
docker compose --profile monolith up -d # 单体模式
docker compose --profile microservices up -d # 微服务模式
```
### 部署模式对比
| 模式 | Profile | 启动服务 | 依赖 | 访问入口 |
|------|---------|----------|------|----------|
| **单体** | `monolith` | `bytech-boot` + MySQL + Redis | 无需 Nacos | `http://localhost:${BOOT_PORT:-8080}` |
| **微服务** | `microservices` | gateway/auth/system/platform/file/ai/job/monitor + xxl-job-admin + Nacos + MySQL + Redis + Nginx | 需 Nacos | `http://localhost:${NGINX_PORT:-80}` |
- **单体模式**：`bytech-boot` 聚合所有业务模块，直连 MySQL + Redis，无需 Nacos / Feign，零网络开销。
- **微服务模式**：各服务经 Nacos 注册发现，由 Gateway 统一入口，前端经 Nginx 反向代理访问。
### 关键配置（`.env`）
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MYSQL_ROOT_PASSWORD` | MySQL root 密码 | - |
| `REDIS_PASSWORD` | Redis 密码（容器内 `requirepass`） | - |
| `NACOS_AUTH_ENABLE` | Nacos 鉴权开关（微服务模式） | `false` |
| `MYSQL_HOST` / `REDIS_HOST` | 容器服务名，默认 `mysql` / `redis` | `mysql` / `redis` |
| `JAVA_XMS` / `JAVA_XMX` | 微服务 JVM 内存（默认中等压力） | `256m` / `512m` |
| `BOOT_JAVA_XMS` / `BOOT_JAVA_XMX` | 单体 JVM 内存（聚合所有模块，建议更大） | `512m` / `1024m` |
| `GATEWAY_PORT` / `BOOT_PORT` / `AUTH_PORT` / `TENANT_PORT` / `SYSTEM_PORT` / `FILE_PORT` / `AI_PORT` / `JOB_PORT` / `MONITOR_PORT` / `NGINX_PORT` | 宿主机端口映射 | `8080` / `8080` / `9001` / `9011` / `9021` / `9031` / `9042` / `9051` / `9041` / `81` |
> 单体模式下，环境变量通过 `SPRING_REDIS_*` / `SA_TOKEN_ALONE_REDIS_*` 自动绑定到 `application.yml`，与容器服务名 `redis` 配套，无需手动改数据库地址。
### 常用命令
```bash
docker compose --profile monolith logs -f bytech-boot # 查看单体日志
docker compose --profile microservices ps # 查看微服务状态
docker compose --profile monolith down # 停止（保留卷）
docker compose --profile monolith down -v # 停止并删除数据卷
```
## 快速开始
### 环境要求
- JDK 17+
- MySQL 8.0+
- Redis 7.x
- Nacos 2.x（微服务模式）
- Maven 3.8+
### 1. 初始化数据库
```sql
-- 创建公共库
CREATE DATABASE bytech_platform DEFAULT CHARACTER SET utf8mb4;
CREATE DATABASE bytech_system DEFAULT CHARACTER SET utf8mb4;
-- 导入表结构
source sql/bytech_platform.sql;
source sql/bytech_system.sql;
```
### 2. 单体模式（快速体验）
```bash
mvn clean package -pl bytech-boot -DskipTests
java -jar bytech-boot/target/bytech-boot-exec.jar --spring.profiles.active=monolith
```
访问 `http://localhost:8080`，默认账号 `admin` / `admin123`。
### 3. 微服务模式
3.1 启动 Nacos + Redis + MySQL
3.2 导入 Nacos 配置（`nacos-configs/dev/` 目录）
3.3 依次启动：
```bash
# Gateway
mvn spring-boot:run -pl bytech-gateway -Dspring.profiles.active=dev
# Auth
mvn spring-boot:run -pl bytech-auth -Dspring.profiles.active=dev
# System
mvn spring-boot:run -pl bytech-modules/bytech-system -Dspring.profiles.active=dev
# Platform
mvn spring-boot:run -pl bytech-modules/bytech-platform -Dspring.profiles.active=dev
# File
mvn spring-boot:run -pl bytech-modules/bytech-file -Dspring.profiles.active=dev
# AI（智能对话：多渠道路由对话 / 渠道管理 / 对话历史）
mvn spring-boot:run -pl bytech-modules/bytech-ai -Dspring.profiles.active=dev
# Job（定时任务：XXL-JOB 分布式调度 / 任务管理 / 执行日志）
mvn spring-boot:run -pl bytech-modules/bytech-job -Dspring.profiles.active=dev
# Monitor（可选，系统监控：服务监控 / Redis 监控 / 在线用户）
mvn spring-boot:run -pl bytech-monitor -Dspring.profiles.active=dev
```
## 项目文档
| 文档 | 说明 |
|------|------|
| [双系统登录机制](docs/双系统同时登录机制.md) | 双 Token + currentLoginType 切换方案 |
| [多租户数据隔离](docs/multi-tenant-design.md) | Schema 级别隔离设计 |
| [API 调用规范](docs/API_CALLING_CONVENTION.md) | Controller implements FeignClient 双模约定 |
| [RBAC 权限模型](docs/RBAC数据库设计与逻辑说明.md) | 平台 + 租户两套 RBAC |
| [前端登录逻辑](docs/前端登录两种系统类型逻辑分析.md) | 前端双系统登录状态管理 |
| [登录逻辑说明](docs/login-logic.md) | 认证流程详解 |
| [数据库规范](docs/database-specification.md) | 建表与命名规范 |
| [系统配置设计](docs/sys_config_design.md) | 参数配置模块设计 |
| [系统监控](docs/system-monitoring.md) | 服务监控 / Redis 监控 / 在线用户 |
| [AI 功能模块](docs/ai-module.md) | 多渠道路由对话 / 渠道管理 / 对话历史 |
| [定时任务模块](docs/job-module.md) | XXL-JOB 分布式调度 / 任务管理 / 执行日志 / 双模适配 |
| [登录验证码设计](docs/captcha-design.md) | 图片 / 短信 / TOTP 统一可插拔验证码架构与实现原理 |
| [WAF 设计](docs/waf-design.md) | 应用内 WAF：双模架构、规则组、灰度上线、四级开关、轻量观测、阶段规划 |
## License
MIT