springbootAI 2.3.7__tar.gz → 2.3.8__tar.gz

{springbootai-2.3.7 → springbootai-2.3.8}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [2.3.8] - 2026-08-24
+
+- 修复配置加载的原子性与数据库 URL 优先级：请求监控不再误落到根目录 `test.db`，SQLite 运行目录会自动创建，显式 URL/驱动/数据库名称按统一优先级生效。
+- 新增可选配置监控（默认关闭），兼容 YAML、环境变量和 Nacos，提供脱敏历史、变更键、来源、耗时与成功/失败信息，并接入 Actuator/Admin 面板。
+- 修复 Nacos 热更新失败后不重试、客户端状态污染和 Web/Actuator/请求监控配置不刷新的问题；热更新现在安全重绑运行时配置。
+- 修复默认 profile 占位符未参与 profile 文件选择的问题，支持自动加载 `application-default.yml`；同时限制 Nacos 请求超时（最多 120 秒）和热刷新间隔（最多 1 小时）。
+- 为 Nacos 服务发现与 RabbitMQ 增加有限连接/请求超时和重试上限，未配置或服务不可用时不会无限阻塞启动；补充 MCP 本机代理兼容、Redis 单次探测和 AI Cache 并发/容量保护。
+- 加固 Spring Cloud Config 可选客户端：容忍空/错误配置层级，限制 timeout、重试次数与退避间隔，避免配置中心异常反向拖垮启动。
+- 补充条件装配注解示例、可选组件超时回归测试，并同步配置元数据与模块文档。
+
 ## [2.3.7] - 2026-08-20
 
 ### PyPI 项目说明修正

{springbootai-2.3.7/springbootAI.egg-info → springbootai-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.7
+Version: 2.3.8
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -187,7 +187,7 @@ SpringBootAI 已提供配套的在线考试认证平台，学习者、团队成
 
 建议的认证准备流程：
 
-1. 先按 README 中的“10 分钟跑通第一个接口”完成本地环境搭建，确认能够创建应用、启动服务并访问 Swagger。
+1. 先按 README 中的“1 分钟跑通第一个接口”完成本地环境搭建，确认能够创建应用、启动服务并访问 Swagger。
 2. 阅读 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)，理解 `@SpringBootApplication`、`@RestController`、`@Service`、`@Autowired`、配置文件和依赖注入的基本用法。
 3. 根据实际使用方向阅读模块文档，例如 Web MVC、ORM、事务、缓存、安全、配置绑定、测试切片、AI、LangChain、LangGraph、MCP 和 Cloud 微服务等。
 4. 运行示例或编写一个小型业务接口，至少覆盖 Controller、Service、配置读取、异常处理、Swagger 文档和数据访问中的若干能力。
@@ -216,90 +216,40 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.3.7`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
+当前版本是 `2.3.8`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
-## 10 分钟跑通第一个接口
+## 1 分钟跑通第一个接口
 
-以下示例不需要数据库、Redis 或大模型 API Key。先创建项目和虚拟环境：
+已安装 Python 3.10、3.11 或 3.12 时，直接执行下面五条命令。示例不需要数据库、Redis、Docker 或大模型 API Key：
 
 ```powershell
-mkdir my-first-app
-cd my-first-app
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-python -m pip install --upgrade pip
-python -m pip install springbootAI
-
-mkdir demo
-mkdir demo\controller
-New-Item demo\__init__.py -ItemType File
-New-Item demo\controller\__init__.py -ItemType File
-```
-
-Linux/macOS 激活命令是 `source .venv/bin/activate`，其余 Python 命令相同。
-
-创建 `demo/Application.py`：
-
-```python
-from springbootai.annotations import SpringBootApplication
-from springbootai.main import run
-
-
-@SpringBootApplication(scan_base_packages=["demo"])
-class Application:
-    pass
-
-
-if __name__ == "__main__":
-    run(Application)
-```
-
-创建 `demo/controller/HelloController.py`：
-
-```python
-from springbootai.annotations import GetMapping, RequestMapping, RestController
-from springbootai.web.swagger import Operation, Tag
-
-
-@Tag(name="入门接口", description="确认应用已经正常运行")
-@RequestMapping("/api")
-@RestController
-class HelloController:
-    @Operation(summary="打招呼")
-    @GetMapping("/hello/{name}")
-    def hello(self, name: str):
-        return {"message": f"Hello, {name}"}
+python -m pip install --upgrade springbootAI
+springbootai init demo --modules web --no-docker --non-interactive
+cd demo
+python -m pip install -r requirements.txt
+python Application.py
 ```
 
-创建 `demo/application.yml`。这里显式关闭暂时用不到的外部资源，避免新手第一次启动就连接数据库：
+`springbootai init demo` 会自动创建 `demo` 项目目录、启动类、配置文件和 Hello 示例接口。`--non-interactive` 表示直接使用默认配置，不进入问答；`--no-docker` 表示本次不生成 Docker 文件。
 
-```yaml
-server:
-  host: 127.0.0.1
-  port: 8080
-
-database:
-  enabled: false
+看到下面的输出就说明启动成功：
 
-redis:
-  enabled: false
+```text
+Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
 ```
 
-在 `demo` 目录的上一层启动：
+保持服务运行，另开终端验证：
 
 ```powershell
-python -m demo.Application
+curl http://127.0.0.1:8000/api/hello/Alice
+curl http://127.0.0.1:8000/actuator/health/liveness
 ```
 
-另开终端验证：
-
-```powershell
-curl http://127.0.0.1:8080/api/hello/Alice
-```
+第一个请求的返回数据中会包含 `"message":"Hello, Alice!"`，健康检查会返回 `"status":"UP"`。浏览器访问 `http://127.0.0.1:8000/docs` 可以直接查看并测试 Swagger 接口。
 
-返回数据中应包含 `"message":"Hello, Alice"`。浏览器访问 `http://127.0.0.1:8080/docs` 可以看到 Swagger 页面。遇到目录、虚拟环境或启动错误时，按[新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)逐步排查。
+生成的业务代码位于 `demo/src/demo/`，主配置文件位于 `demo/config/application.yml`。完整参数见 [CLI 模块指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CLI_MODULE.md)，遇到启动问题时按[新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)排查。
 
 ---
 
@@ -397,10 +347,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.7 |
-| `springbootai.orm.pymybatis` | 2.3.7 |
-| `springbootai.ai` AI 模块 | 2.3.7 |
-| `springbootai.langchain` LangChain 模块 | 2.3.7 |
+| `springbootai` 框架 API | 2.3.8 |
+| `springbootai.orm.pymybatis` | 2.3.8 |
+| `springbootai.ai` AI 模块 | 2.3.8 |
+| `springbootai.langchain` LangChain 模块 | 2.3.8 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -765,14 +715,30 @@ Profile 用于 Bean 过滤和生产安全校验。多环境配置可使用以下
 | `/actuator/admin` | **Spring Boot Admin 风格可视化面板**（浏览器打开即用，每 30 秒自动刷新） |
 | `/actuator/prometheus` | **Prometheus 文本格式指标**（供 Prometheus Server 抓取） |
 | `/actuator/sysmetrics` | **进程级系统指标**（RSS/CPU/线程/FD，供 Admin 面板 JS 调用） |
+| `/actuator/config-monitor` | 配置加载与 Nacos 热刷新历史（`management.config-monitor.enabled=true` 后启用，默认关闭） |
+
+`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建数据库文件。
+
+配置监控默认关闭。需要排查配置来源或热更新时，可在 YAML、环境变量或 Nacos 中设置：
+
+```yaml
+management:
+  config-monitor:
+    enabled: true
+    include-values: false       # 生产环境建议保持 false
+    history-size: 100
+    refresh-events: true
+```
 
-`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建 `test.db`。
+开启后访问受 Actuator 鉴权保护的 `/actuator/config-monitor`，或直接查看 Admin
+面板中的“配置刷新监控”卡片。关闭时不保留历史，也不读取配置值。
 
 > 详见 [ACTUATOR_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ACTUATOR_MODULE.md) 第四章（Spring Boot Admin 面板）与第五章（Prometheus + Grafana 工业级监控）。
 
 > **⚠️ 新手常见错误**：
-> - ❌ 错误："我改了 YAML，重新请求接口怎么没生效？"
-> - ✅ 正解：修改 YAML 后需要**重启应用**（`Ctrl+C` 停掉再重新运行）。YAML 配置是启动时一次性读取的。
+> - ❌ 错误："我改了本地 YAML，重新请求接口怎么没生效？"
+> - ✅ 正解：本地 YAML 是启动时读取的，修改后需要重启应用；Nacos 配置只有在启用
+>   `NACOS_CONFIG_ENABLED=true` 且 `refresh-enabled=true` 时才会按轮询间隔热刷新。
 
 ---
 
@@ -1715,9 +1681,13 @@ gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8080 myapp.asgi:app
 |---------|------|--------|
 | `SERVER_PORT` | 服务端口 | 8080 |
 | `JWT_SECRET_KEY` | JWT 密钥 | spring-python-secret-key-change-in-production |
-| `DB_URL` | 数据库连接 URL | sqlite:///./test.db |
+| `DB_URL` | 数据库连接 URL | 未设置时使用 `sqlite:///./runtime/springbootai.db` |
 | `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | Redis 连接 | localhost/6379/空 |
 | `NACOS_SERVER` | Nacos 地址 | localhost:8848 |
+| `NACOS_TIMEOUT` / `DISCOVERY_TIMEOUT` | Nacos 服务发现单次 HTTP 超时（秒） | 3（最大60） |
+| `RABBITMQ_CONNECTION_TIMEOUT` | RabbitMQ 建连默认超时（秒） | 5 |
+| `RABBITMQ_SOCKET_TIMEOUT` / `RABBITMQ_STACK_TIMEOUT` | RabbitMQ TCP/AMQP 握手超时（秒） | 5/5 |
+| `RABBITMQ_CONNECTION_ATTEMPTS` | RabbitMQ 建连尝试次数 | 1 |
 | `SPRING_DISABLE_DOCKER_IP_DETECT` | 禁用容器 IP 检测 | 0 |
 
 ### 14.5 验证部署 & 故障排查

{springbootai-2.3.7 → springbootai-2.3.8}/README.md

@@ -25,7 +25,7 @@ SpringBootAI 已提供配套的在线考试认证平台，学习者、团队成
 
 建议的认证准备流程：
 
-1. 先按 README 中的“10 分钟跑通第一个接口”完成本地环境搭建，确认能够创建应用、启动服务并访问 Swagger。
+1. 先按 README 中的“1 分钟跑通第一个接口”完成本地环境搭建，确认能够创建应用、启动服务并访问 Swagger。
 2. 阅读 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)，理解 `@SpringBootApplication`、`@RestController`、`@Service`、`@Autowired`、配置文件和依赖注入的基本用法。
 3. 根据实际使用方向阅读模块文档，例如 Web MVC、ORM、事务、缓存、安全、配置绑定、测试切片、AI、LangChain、LangGraph、MCP 和 Cloud 微服务等。
 4. 运行示例或编写一个小型业务接口，至少覆盖 Controller、Service、配置读取、异常处理、Swagger 文档和数据访问中的若干能力。
@@ -54,90 +54,40 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.3.7`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
+当前版本是 `2.3.8`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
-## 10 分钟跑通第一个接口
+## 1 分钟跑通第一个接口
 
-以下示例不需要数据库、Redis 或大模型 API Key。先创建项目和虚拟环境：
+已安装 Python 3.10、3.11 或 3.12 时，直接执行下面五条命令。示例不需要数据库、Redis、Docker 或大模型 API Key：
 
 ```powershell
-mkdir my-first-app
-cd my-first-app
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-python -m pip install --upgrade pip
-python -m pip install springbootAI
-
-mkdir demo
-mkdir demo\controller
-New-Item demo\__init__.py -ItemType File
-New-Item demo\controller\__init__.py -ItemType File
-```
-
-Linux/macOS 激活命令是 `source .venv/bin/activate`，其余 Python 命令相同。
-
-创建 `demo/Application.py`：
-
-```python
-from springbootai.annotations import SpringBootApplication
-from springbootai.main import run
-
-
-@SpringBootApplication(scan_base_packages=["demo"])
-class Application:
-    pass
-
-
-if __name__ == "__main__":
-    run(Application)
-```
-
-创建 `demo/controller/HelloController.py`：
-
-```python
-from springbootai.annotations import GetMapping, RequestMapping, RestController
-from springbootai.web.swagger import Operation, Tag
-
-
-@Tag(name="入门接口", description="确认应用已经正常运行")
-@RequestMapping("/api")
-@RestController
-class HelloController:
-    @Operation(summary="打招呼")
-    @GetMapping("/hello/{name}")
-    def hello(self, name: str):
-        return {"message": f"Hello, {name}"}
+python -m pip install --upgrade springbootAI
+springbootai init demo --modules web --no-docker --non-interactive
+cd demo
+python -m pip install -r requirements.txt
+python Application.py
 ```
 
-创建 `demo/application.yml`。这里显式关闭暂时用不到的外部资源，避免新手第一次启动就连接数据库：
+`springbootai init demo` 会自动创建 `demo` 项目目录、启动类、配置文件和 Hello 示例接口。`--non-interactive` 表示直接使用默认配置，不进入问答；`--no-docker` 表示本次不生成 Docker 文件。
 
-```yaml
-server:
-  host: 127.0.0.1
-  port: 8080
-
-database:
-  enabled: false
+看到下面的输出就说明启动成功：
 
-redis:
-  enabled: false
+```text
+Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
 ```
 
-在 `demo` 目录的上一层启动：
+保持服务运行，另开终端验证：
 
 ```powershell
-python -m demo.Application
+curl http://127.0.0.1:8000/api/hello/Alice
+curl http://127.0.0.1:8000/actuator/health/liveness
 ```
 
-另开终端验证：
-
-```powershell
-curl http://127.0.0.1:8080/api/hello/Alice
-```
+第一个请求的返回数据中会包含 `"message":"Hello, Alice!"`，健康检查会返回 `"status":"UP"`。浏览器访问 `http://127.0.0.1:8000/docs` 可以直接查看并测试 Swagger 接口。
 
-返回数据中应包含 `"message":"Hello, Alice"`。浏览器访问 `http://127.0.0.1:8080/docs` 可以看到 Swagger 页面。遇到目录、虚拟环境或启动错误时，按[新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)逐步排查。
+生成的业务代码位于 `demo/src/demo/`，主配置文件位于 `demo/config/application.yml`。完整参数见 [CLI 模块指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CLI_MODULE.md)，遇到启动问题时按[新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)排查。
 
 ---
 
@@ -235,10 +185,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.7 |
-| `springbootai.orm.pymybatis` | 2.3.7 |
-| `springbootai.ai` AI 模块 | 2.3.7 |
-| `springbootai.langchain` LangChain 模块 | 2.3.7 |
+| `springbootai` 框架 API | 2.3.8 |
+| `springbootai.orm.pymybatis` | 2.3.8 |
+| `springbootai.ai` AI 模块 | 2.3.8 |
+| `springbootai.langchain` LangChain 模块 | 2.3.8 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -603,14 +553,30 @@ Profile 用于 Bean 过滤和生产安全校验。多环境配置可使用以下
 | `/actuator/admin` | **Spring Boot Admin 风格可视化面板**（浏览器打开即用，每 30 秒自动刷新） |
 | `/actuator/prometheus` | **Prometheus 文本格式指标**（供 Prometheus Server 抓取） |
 | `/actuator/sysmetrics` | **进程级系统指标**（RSS/CPU/线程/FD，供 Admin 面板 JS 调用） |
+| `/actuator/config-monitor` | 配置加载与 Nacos 热刷新历史（`management.config-monitor.enabled=true` 后启用，默认关闭） |
+
+`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建数据库文件。
+
+配置监控默认关闭。需要排查配置来源或热更新时，可在 YAML、环境变量或 Nacos 中设置：
+
+```yaml
+management:
+  config-monitor:
+    enabled: true
+    include-values: false       # 生产环境建议保持 false
+    history-size: 100
+    refresh-events: true
+```
 
-`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建 `test.db`。
+开启后访问受 Actuator 鉴权保护的 `/actuator/config-monitor`，或直接查看 Admin
+面板中的“配置刷新监控”卡片。关闭时不保留历史，也不读取配置值。
 
 > 详见 [ACTUATOR_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ACTUATOR_MODULE.md) 第四章（Spring Boot Admin 面板）与第五章（Prometheus + Grafana 工业级监控）。
 
 > **⚠️ 新手常见错误**：
-> - ❌ 错误："我改了 YAML，重新请求接口怎么没生效？"
-> - ✅ 正解：修改 YAML 后需要**重启应用**（`Ctrl+C` 停掉再重新运行）。YAML 配置是启动时一次性读取的。
+> - ❌ 错误："我改了本地 YAML，重新请求接口怎么没生效？"
+> - ✅ 正解：本地 YAML 是启动时读取的，修改后需要重启应用；Nacos 配置只有在启用
+>   `NACOS_CONFIG_ENABLED=true` 且 `refresh-enabled=true` 时才会按轮询间隔热刷新。
 
 ---
 
@@ -1553,9 +1519,13 @@ gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8080 myapp.asgi:app
 |---------|------|--------|
 | `SERVER_PORT` | 服务端口 | 8080 |
 | `JWT_SECRET_KEY` | JWT 密钥 | spring-python-secret-key-change-in-production |
-| `DB_URL` | 数据库连接 URL | sqlite:///./test.db |
+| `DB_URL` | 数据库连接 URL | 未设置时使用 `sqlite:///./runtime/springbootai.db` |
 | `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | Redis 连接 | localhost/6379/空 |
 | `NACOS_SERVER` | Nacos 地址 | localhost:8848 |
+| `NACOS_TIMEOUT` / `DISCOVERY_TIMEOUT` | Nacos 服务发现单次 HTTP 超时（秒） | 3（最大60） |
+| `RABBITMQ_CONNECTION_TIMEOUT` | RabbitMQ 建连默认超时（秒） | 5 |
+| `RABBITMQ_SOCKET_TIMEOUT` / `RABBITMQ_STACK_TIMEOUT` | RabbitMQ TCP/AMQP 握手超时（秒） | 5/5 |
+| `RABBITMQ_CONNECTION_ATTEMPTS` | RabbitMQ 建连尝试次数 | 1 |
 | `SPRING_DISABLE_DOCKER_IP_DETECT` | 禁用容器 IP 检测 | 0 |
 
 ### 14.5 验证部署 & 故障排查

{springbootai-2.3.7 → springbootai-2.3.8}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # Distribution name: springbootAI (pip install springbootAI); import package: springbootai.
 name = "springbootAI"
-version = "2.3.7"
+version = "2.3.8"
 description = "Spring-style Python framework with Web, ORM, Cloud and AI integrations"
 readme = "README.md"
 license = "MIT"

{springbootai-2.3.7 → springbootai-2.3.8/springbootAI.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.7
+Version: 2.3.8
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -187,7 +187,7 @@ SpringBootAI 已提供配套的在线考试认证平台，学习者、团队成
 
 建议的认证准备流程：
 
-1. 先按 README 中的“10 分钟跑通第一个接口”完成本地环境搭建，确认能够创建应用、启动服务并访问 Swagger。
+1. 先按 README 中的“1 分钟跑通第一个接口”完成本地环境搭建，确认能够创建应用、启动服务并访问 Swagger。
 2. 阅读 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)，理解 `@SpringBootApplication`、`@RestController`、`@Service`、`@Autowired`、配置文件和依赖注入的基本用法。
 3. 根据实际使用方向阅读模块文档，例如 Web MVC、ORM、事务、缓存、安全、配置绑定、测试切片、AI、LangChain、LangGraph、MCP 和 Cloud 微服务等。
 4. 运行示例或编写一个小型业务接口，至少覆盖 Controller、Service、配置读取、异常处理、Swagger 文档和数据访问中的若干能力。
@@ -216,90 +216,40 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.3.7`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
+当前版本是 `2.3.8`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
-## 10 分钟跑通第一个接口
+## 1 分钟跑通第一个接口
 
-以下示例不需要数据库、Redis 或大模型 API Key。先创建项目和虚拟环境：
+已安装 Python 3.10、3.11 或 3.12 时，直接执行下面五条命令。示例不需要数据库、Redis、Docker 或大模型 API Key：
 
 ```powershell
-mkdir my-first-app
-cd my-first-app
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-python -m pip install --upgrade pip
-python -m pip install springbootAI
-
-mkdir demo
-mkdir demo\controller
-New-Item demo\__init__.py -ItemType File
-New-Item demo\controller\__init__.py -ItemType File
-```
-
-Linux/macOS 激活命令是 `source .venv/bin/activate`，其余 Python 命令相同。
-
-创建 `demo/Application.py`：
-
-```python
-from springbootai.annotations import SpringBootApplication
-from springbootai.main import run
-
-
-@SpringBootApplication(scan_base_packages=["demo"])
-class Application:
-    pass
-
-
-if __name__ == "__main__":
-    run(Application)
-```
-
-创建 `demo/controller/HelloController.py`：
-
-```python
-from springbootai.annotations import GetMapping, RequestMapping, RestController
-from springbootai.web.swagger import Operation, Tag
-
-
-@Tag(name="入门接口", description="确认应用已经正常运行")
-@RequestMapping("/api")
-@RestController
-class HelloController:
-    @Operation(summary="打招呼")
-    @GetMapping("/hello/{name}")
-    def hello(self, name: str):
-        return {"message": f"Hello, {name}"}
+python -m pip install --upgrade springbootAI
+springbootai init demo --modules web --no-docker --non-interactive
+cd demo
+python -m pip install -r requirements.txt
+python Application.py
 ```
 
-创建 `demo/application.yml`。这里显式关闭暂时用不到的外部资源，避免新手第一次启动就连接数据库：
+`springbootai init demo` 会自动创建 `demo` 项目目录、启动类、配置文件和 Hello 示例接口。`--non-interactive` 表示直接使用默认配置，不进入问答；`--no-docker` 表示本次不生成 Docker 文件。
 
-```yaml
-server:
-  host: 127.0.0.1
-  port: 8080
-
-database:
-  enabled: false
+看到下面的输出就说明启动成功：
 
-redis:
-  enabled: false
+```text
+Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
 ```
 
-在 `demo` 目录的上一层启动：
+保持服务运行，另开终端验证：
 
 ```powershell
-python -m demo.Application
+curl http://127.0.0.1:8000/api/hello/Alice
+curl http://127.0.0.1:8000/actuator/health/liveness
 ```
 
-另开终端验证：
-
-```powershell
-curl http://127.0.0.1:8080/api/hello/Alice
-```
+第一个请求的返回数据中会包含 `"message":"Hello, Alice!"`，健康检查会返回 `"status":"UP"`。浏览器访问 `http://127.0.0.1:8000/docs` 可以直接查看并测试 Swagger 接口。
 
-返回数据中应包含 `"message":"Hello, Alice"`。浏览器访问 `http://127.0.0.1:8080/docs` 可以看到 Swagger 页面。遇到目录、虚拟环境或启动错误时，按[新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)逐步排查。
+生成的业务代码位于 `demo/src/demo/`，主配置文件位于 `demo/config/application.yml`。完整参数见 [CLI 模块指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CLI_MODULE.md)，遇到启动问题时按[新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md)排查。
 
 ---
 
@@ -397,10 +347,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.7 |
-| `springbootai.orm.pymybatis` | 2.3.7 |
-| `springbootai.ai` AI 模块 | 2.3.7 |
-| `springbootai.langchain` LangChain 模块 | 2.3.7 |
+| `springbootai` 框架 API | 2.3.8 |
+| `springbootai.orm.pymybatis` | 2.3.8 |
+| `springbootai.ai` AI 模块 | 2.3.8 |
+| `springbootai.langchain` LangChain 模块 | 2.3.8 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -765,14 +715,30 @@ Profile 用于 Bean 过滤和生产安全校验。多环境配置可使用以下
 | `/actuator/admin` | **Spring Boot Admin 风格可视化面板**（浏览器打开即用，每 30 秒自动刷新） |
 | `/actuator/prometheus` | **Prometheus 文本格式指标**（供 Prometheus Server 抓取） |
 | `/actuator/sysmetrics` | **进程级系统指标**（RSS/CPU/线程/FD，供 Admin 面板 JS 调用） |
+| `/actuator/config-monitor` | 配置加载与 Nacos 热刷新历史（`management.config-monitor.enabled=true` 后启用，默认关闭） |
+
+`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建数据库文件。
+
+配置监控默认关闭。需要排查配置来源或热更新时，可在 YAML、环境变量或 Nacos 中设置：
+
+```yaml
+management:
+  config-monitor:
+    enabled: true
+    include-values: false       # 生产环境建议保持 false
+    history-size: 100
+    refresh-events: true
+```
 
-`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建 `test.db`。
+开启后访问受 Actuator 鉴权保护的 `/actuator/config-monitor`，或直接查看 Admin
+面板中的“配置刷新监控”卡片。关闭时不保留历史，也不读取配置值。
 
 > 详见 [ACTUATOR_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ACTUATOR_MODULE.md) 第四章（Spring Boot Admin 面板）与第五章（Prometheus + Grafana 工业级监控）。
 
 > **⚠️ 新手常见错误**：
-> - ❌ 错误："我改了 YAML，重新请求接口怎么没生效？"
-> - ✅ 正解：修改 YAML 后需要**重启应用**（`Ctrl+C` 停掉再重新运行）。YAML 配置是启动时一次性读取的。
+> - ❌ 错误："我改了本地 YAML，重新请求接口怎么没生效？"
+> - ✅ 正解：本地 YAML 是启动时读取的，修改后需要重启应用；Nacos 配置只有在启用
+>   `NACOS_CONFIG_ENABLED=true` 且 `refresh-enabled=true` 时才会按轮询间隔热刷新。
 
 ---
 
@@ -1715,9 +1681,13 @@ gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8080 myapp.asgi:app
 |---------|------|--------|
 | `SERVER_PORT` | 服务端口 | 8080 |
 | `JWT_SECRET_KEY` | JWT 密钥 | spring-python-secret-key-change-in-production |
-| `DB_URL` | 数据库连接 URL | sqlite:///./test.db |
+| `DB_URL` | 数据库连接 URL | 未设置时使用 `sqlite:///./runtime/springbootai.db` |
 | `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | Redis 连接 | localhost/6379/空 |
 | `NACOS_SERVER` | Nacos 地址 | localhost:8848 |
+| `NACOS_TIMEOUT` / `DISCOVERY_TIMEOUT` | Nacos 服务发现单次 HTTP 超时（秒） | 3（最大60） |
+| `RABBITMQ_CONNECTION_TIMEOUT` | RabbitMQ 建连默认超时（秒） | 5 |
+| `RABBITMQ_SOCKET_TIMEOUT` / `RABBITMQ_STACK_TIMEOUT` | RabbitMQ TCP/AMQP 握手超时（秒） | 5/5 |
+| `RABBITMQ_CONNECTION_ATTEMPTS` | RabbitMQ 建连尝试次数 | 1 |
 | `SPRING_DISABLE_DOCKER_IP_DETECT` | 禁用容器 IP 检测 | 0 |
 
 ### 14.5 验证部署 & 故障排查

{springbootai-2.3.7 → springbootai-2.3.8}/springbootAI.egg-info/SOURCES.txt

@@ -71,6 +71,7 @@ springbootai/cloud/transaction_store.py
 springbootai/config/__init__.py
 springbootai/config/binding.py
 springbootai/config/config_loader.py
+springbootai/config/config_monitor.py
 springbootai/config/spring-configuration-metadata.json
 springbootai/context/__init__.py
 springbootai/context/application_context.py
@@ -282,7 +283,9 @@ tests/test_compositional_annotations.py
 tests/test_conditional_annotations.py
 tests/test_config_binding.py
 tests/test_config_center.py
+tests/test_config_center_hardening.py
 tests/test_config_fixes_185.py
+tests/test_config_monitor.py
 tests/test_connection_resilience.py
 tests/test_core.py
 tests/test_core_annotations_full.py
@@ -315,6 +318,7 @@ tests/test_nacos_config.py
 tests/test_new_annotations.py
 tests/test_new_features.py
 tests/test_oauth2.py
+tests/test_optional_component_timeouts.py
 tests/test_orm_pymybatis_full.py
 tests/test_production_readiness.py
 tests/test_pymybatis_configuration_hardening.py

{springbootai-2.3.7 → springbootai-2.3.8}/springbootai/__init__.py

@@ -19,7 +19,7 @@ from .config import *
 from .utils import *
 from .main import create_app, run, SpringApplication, run_cli
 
-__version__ = "2.3.7"
+__version__ = "2.3.8"
 __author__ = "yuconggen"
 __license__ = "MIT"
 

{springbootai-2.3.7 → springbootai-2.3.8}/springbootai/ai/__init__.py

@@ -54,7 +54,7 @@ from springbootai.ai.observability import AIMetrics, ai_metrics
 from springbootai.ai.autoconfig import AIProperties, bind_ai_config, configure_ai
 from springbootai.ai.annotation_runtime import ContentModerationError
 
-__version__ = "2.3.7"
+__version__ = "2.3.8"
 
 __all__ = [
     # core