springbootAI 2.3.7__tar.gz → 2.3.9__tar.gz

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

@@ -1,5 +1,24 @@
 # Changelog
 
+## [2.3.9] - 2026-08-28
+
+- 加固 OpenAI 兼容接口与 Ollama 的同步/异步流式协议：校验终止帧、错误信封和畸形响应，限制事件与响应大小，并完善超时、有限重试、重定向拒绝及 SDK 重试边界。
+- 修复 AI 异步流阻塞事件循环、请求参数覆盖受保护字段、输出 Token 上限绕过、工具调用闭环和多租户 Memory/RAG 隔离等问题。
+- 加固 Feign、Gateway、Config Center、Admin 与 Discovery：正确释放响应、执行路由谓词和过滤器、过滤逐跳头、传播请求 ID，并增加路径、响应大小、故障回退与生命周期保护。
+- 新增统一日志脱敏和日志注入防护，覆盖异常链、Bearer/Basic/Cookie、云事件、Nacos、Seata 与 SkyWalking，避免敏感负载进入日志或健康响应。
+- 修复原子脚手架写入、TextReader 文件边界、DevTools 停止/重启语义、SkyWalking 显式初始化和 Banner 版本读取错误。
+- 新增企业加固回归测试；完整测试结果为 3170 passed、11 skipped、0 failed，Bandit 中高危扫描为 0。
+
+## [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.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.7
+Version: 2.3.9
 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.9`；支持 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.9 |
+| `springbootai.orm.pymybatis` | 2.3.9 |
+| `springbootai.ai` AI 模块 | 2.3.9 |
+| `springbootai.langchain` LangChain 模块 | 2.3.9 |
 | 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`，不会创建 `test.db`。
+`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建数据库文件。
+
+配置监控默认关闭。需要排查配置来源或热更新时，可在 YAML、环境变量或 Nacos 中设置：
+
+```yaml
+management:
+  config-monitor:
+    enabled: true
+    include-values: false       # 生产环境建议保持 false
+    history-size: 100
+    refresh-events: true
+```
+
+开启后访问受 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` 时才会按轮询间隔热刷新。
 
 ---
 
@@ -971,6 +937,16 @@ class InitService:
             self.connection.close()
 ```
 
+每个 HTTP 请求都会获得 `X-Request-ID`（可通过
+`server.request-id.header` 修改），该值会写回响应并自动进入框架日志，Feign
+和 Gateway 也会向下游透传。日志会遮蔽 Bearer Token、API Key、密码、Cookie
+等常见敏感字段；`logging.diagnose` 默认关闭，避免异常帧局部变量泄密。
+
+声明式 Feign 客户端默认复用连接池，对幂等请求执行有限退避重试，并支持连接/
+读取超时与响应大小限制。直接读取 RAG 文本文件时建议使用
+`TextReader.from_file(path, max_bytes=...)`，文件不存在或超限会明确失败，不会把
+错误路径误当成内联文本。
+
 ### 5.7 应用事件
 
 ```python
@@ -1715,9 +1691,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 验证部署 & 故障排查
@@ -1925,9 +1905,13 @@ export LOG_DIR=logs
 
 # AI 模块
 export AI_PROVIDER=openai
-export AI_ALLOW_FAKE=true
+export AI_ALLOW_FAKE=false
 export OPENAI_API_KEY=sk-xxx
 export OPENAI_CHAT_MODEL=gpt-4o-mini
+export AI_REQUEST_TIMEOUT_SECONDS=60
+export AI_MAX_OUTPUT_TOKENS=4096
+export AI_MAX_TOTAL_TOKENS=100000
+export AI_MAX_TOOL_ITERATIONS=5
 export OLLAMA_BASE_URL=http://localhost:11434
 export OLLAMA_CHAT_MODEL=llama3
 

{springbootai-2.3.7 → springbootai-2.3.9}/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.9`；支持 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.9 |
+| `springbootai.orm.pymybatis` | 2.3.9 |
+| `springbootai.ai` AI 模块 | 2.3.9 |
+| `springbootai.langchain` LangChain 模块 | 2.3.9 |
 | 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`，不会创建 `test.db`。
+`database.enabled: false` 时数据库状态为 `DISABLED`，不会创建数据库文件。
+
+配置监控默认关闭。需要排查配置来源或热更新时，可在 YAML、环境变量或 Nacos 中设置：
+
+```yaml
+management:
+  config-monitor:
+    enabled: true
+    include-values: false       # 生产环境建议保持 false
+    history-size: 100
+    refresh-events: true
+```
+
+开启后访问受 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` 时才会按轮询间隔热刷新。
 
 ---
 
@@ -809,6 +775,16 @@ class InitService:
             self.connection.close()
 ```
 
+每个 HTTP 请求都会获得 `X-Request-ID`（可通过
+`server.request-id.header` 修改），该值会写回响应并自动进入框架日志，Feign
+和 Gateway 也会向下游透传。日志会遮蔽 Bearer Token、API Key、密码、Cookie
+等常见敏感字段；`logging.diagnose` 默认关闭，避免异常帧局部变量泄密。
+
+声明式 Feign 客户端默认复用连接池，对幂等请求执行有限退避重试，并支持连接/
+读取超时与响应大小限制。直接读取 RAG 文本文件时建议使用
+`TextReader.from_file(path, max_bytes=...)`，文件不存在或超限会明确失败，不会把
+错误路径误当成内联文本。
+
 ### 5.7 应用事件
 
 ```python
@@ -1553,9 +1529,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 验证部署 & 故障排查
@@ -1763,9 +1743,13 @@ export LOG_DIR=logs
 
 # AI 模块
 export AI_PROVIDER=openai
-export AI_ALLOW_FAKE=true
+export AI_ALLOW_FAKE=false
 export OPENAI_API_KEY=sk-xxx
 export OPENAI_CHAT_MODEL=gpt-4o-mini
+export AI_REQUEST_TIMEOUT_SECONDS=60
+export AI_MAX_OUTPUT_TOKENS=4096
+export AI_MAX_TOTAL_TOKENS=100000
+export AI_MAX_TOOL_ITERATIONS=5
 export OLLAMA_BASE_URL=http://localhost:11434
 export OLLAMA_CHAT_MODEL=llama3
 

{springbootai-2.3.7 → springbootai-2.3.9}/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.9"
 description = "Spring-style Python framework with Web, ORM, Cloud and AI integrations"
 readme = "README.md"
 license = "MIT"
@@ -256,6 +256,7 @@ full = [
 
 [tool.pytest.ini_options]
 pythonpath = [".", "examples"]
+testpaths = ["tests"]
 filterwarnings = [
     # 闈欓粯 langchain_classic 寮冪敤鍛婅鍜?community sunset 鍛婅
     # 鍘熷洜锛氭湰椤圭洰鏈夋剰閿佸畾 langchain classic (1.x) API锛岃繖浜涙槸棰勬湡鍐呯殑妗嗘灦绾у憡璀?