diff --git a/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md
index 1725b02..79eff01 100644
--- a/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md
+++ b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md
@@ -28,7 +28,9 @@ cd ai_knowledge_base_v2
 docker compose -f docker-compose.dev.yml up --build
 ```
 
-如果用户端问答需要直读飞书知识库，需要在启动前配置后端运行环境变量：
+如果用户端问答需要直读飞书知识库，优先在管理后台“系统设置 / 外部服务”中配置飞书 AppID 和 AppSecret，保存后即可生效，不需要重建容器。
+
+也可以在启动前通过后端运行环境变量配置，作为系统设置为空时的兜底：
 
 ```bash
 export FEISHU_APP_ID=你的飞书应用AppID
@@ -36,7 +38,7 @@ export FEISHU_APP_SECRET=你的飞书应用AppSecret
 docker compose -f docker-compose.dev.yml up -d --build backend user-client admin-web
 ```
 
-也可以在 `ai_knowledge_base_v2/.env` 中配置 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 和 `FEISHU_SEARCH_URL`。后台“知识库管理”只维护 SpaceID、NodeID 和启用状态；飞书应用凭证不存放在知识库记录中。若使用独立飞书检索适配服务，则在后台“系统配置”填写飞书检索服务地址，后端会优先调用该地址。
+也可以在 `ai_knowledge_base_v2/.env` 中配置 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 和 `FEISHU_SEARCH_URL`。后台“知识库管理”只维护 SpaceID、NodeID 和启用状态；飞书应用凭证在后台“系统设置”维护，不存放在知识库记录中。若使用独立飞书检索适配服务，则在后台“系统配置”填写飞书检索服务地址，后端会优先调用该地址。
 
 默认地址：
 
diff --git a/ai_knowledge_base_v2/development_records/2026-07-08-feishu-credential-settings.md b/ai_knowledge_base_v2/development_records/2026-07-08-feishu-credential-settings.md
new file mode 100644
index 0000000..a9301ae
--- /dev/null
+++ b/ai_knowledge_base_v2/development_records/2026-07-08-feishu-credential-settings.md
@@ -0,0 +1,39 @@
+# 飞书应用凭证改为系统设置维护
+
+## 背景
+
+用户端问答已经改为真实知识库检索链路，不再使用知识库 mock。当前后台“知识库管理”只能配置飞书知识库的 `SpaceID`、`NodeID` 和启用状态；后端读取飞书内容时还需要飞书应用的 `AppID` 和 `AppSecret`。
+
+此前实现只支持通过部署环境变量配置：
+
+- `FEISHU_APP_ID`
+- `FEISHU_APP_SECRET`
+
+这导致本地联调时容易误解为“后台已经配置了飞书知识库，所以凭证也已经配置完成”。
+
+## 调整决定
+
+从 2026-07-08 起，飞书应用凭证也放入后台“系统设置”中维护：
+
+- `feishu_app_id`：飞书应用 AppID。
+- `feishu_app_secret`：飞书应用 AppSecret。
+
+后端读取优先级：
+
+1. 优先读取数据库 `sys_system_config` 中的系统设置。
+2. 如果系统设置为空，再回退读取环境变量 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`。
+
+## 交互要求
+
+- 系统设置页在“外部服务”分组展示飞书 AppID 和 AppSecret。
+- AppSecret 输入框使用密码输入样式，避免页面直接明文展示。
+- 保存后问答链路应立即使用新的配置，不需要重建容器。
+
+## 风险与后续优化
+
+当前系统配置表会保存明文配置值。为了快速完成一期联调，先按现有 `sys_system_config` 机制落地；后续生产化时建议补充：
+
+1. 对密钥类配置做加密存储。
+2. 列表读取时对密钥类配置做脱敏展示。
+3. 操作日志避免记录密钥原值。
+4. 支持密钥更新时“留空表示不覆盖旧值”的交互。