docs：添加常见问题和挑战实践教程

Author: greenyhsj

docs/faq/install_configuration.md

@@ -0,0 +1,41 @@
+# 安装部署以及启动问题
+
+## 1 安装 MaxKB 过程报错 docker-compose--X.XX.X 无法启动或者访问服务
+
+!!! Abstract ""
+    Docker 版本太老可能会导致安装失败，建议环境建议使用安装包内的 Docker。安装包所使用的 Docker 版本为 27.2.0、Compose 版本为 v2.29.2。
+
+
+## 2 离线部署提示 failed to cast to expected type: strconv.ParseInt: parsing "2G"
+
+!!! Abstract ""
+    在配置文件中内存设置格式存在问题。打开配置文件 docker-compose-pgsql.yml，找到 services.pgsql.mem_limit 的设置项。 将内存设置值从 "2G" 修改为小写的 "2g"，执行 mkctl reload 命令重新加载配置。
+
+## 3 升级过程提示 ModuleNotFoundError: No module named 'XXX'
+
+!!! Abstract ""
+    某些旧版本的依赖包与新版本不兼容，导致系统无法正常运行。进入依赖包的存储目录：
+    执行以下命令，创建模型：
+    ```
+    cd /opt/maxkb/python-packages
+    ```
+    找到导致依赖冲突的包，通常通过查看错误日志来确定具体冲突的包名。完成依赖包的清理后，重启服务 mkctl restart 以确保更改生效。
+
+## 4 PostgreSQL 超过最大客户端连接数,提示 too many clients already 的错误
+
+!!! Abstract ""
+    这表明当前配置的客户端连接数已达到上限，需要调整配置以允许更多的连接。进入 PostgreSQL 配置文件所在的目录：
+    ```
+    cd /opt/maxkb/data
+    ```
+    找到 postgresql.conf 文件中找到 max_connections 参数，将其值设置为所需的连接数。例如，将最大连接数设置为 200
+    ```
+    max_connections = 200
+    ```
+    停止当前运行的 MaxKB 服务，删除 PostgreSQL 容器，：
+    ```
+    docker stop maxkb
+
+    docker rm maxkb
+    ```
+    执行 mkctl reload 重新加载服务配置并启动服务。

docs/faq/system_management.md

@@ -0,0 +1,110 @@
+# 系统管理
+
+## 1 用户管理
+
+### 1.1 忘记了登录密码如何处理
+
+!!! Abstract ""
+    **非 admin 用户忘记密码**：
+
+    - 已设置邮箱绑定：如果用户已设置邮箱并完成绑定，可在个人信息页面通过【修改密码】功能进行密码修改与找回。
+    - 未设置邮箱绑定：若用户未设置邮箱绑定，可由 admin 管理人员登录系统，在【用户管理】页面中，找到对应用户并直接修改其密码，从而帮助用户找回密码。
+
+!!! Abstract ""
+    **admin 用户忘记密码**：  
+    如果已配置邮箱设置，可在登录页面点击【忘记密码】进行密码找回。若未配置邮箱，则需通过修改数据库将密码恢复为默认密码。操作步骤如下：  
+    在线安装进入 MaxKB 容器（若是离线安装包，请进入 pgsql 容器） 
+
+    ```
+    docker exec -it maxkb bash
+    ```
+
+    登录 PgSQL
+    ```
+    psql -Uroot
+    ```
+    进入 maxkb数据库
+    ```
+    \c maxkb;
+    ```
+    连接到数据库后，执行下面的 SQL 语句可以将用户 admin 的密码重置为 MaxKB@123..
+    ```
+    update  "public"."user" set password='d880e722c47a34d8e9fce789fc62389d' where username='admin';
+    ```
+
+    **注意：找回 admin 密码后优先配置邮箱设置，以便下次忘记密码时能直接使用【忘记密码】功能进行找回。**
+
+
+
+
+### 1.2 编辑用户时没有权限访问
+
+!!! Abstract ""
+    网关配置中未对 PUT 方法进行放行，从而导致权限验证失败。
+
+![doc](../img/FAQ/报错没有权限.png){width="900px"}
+    
+
+## 2 模型对接
+
+### 2.1 对接 Ollama 时提示 API 域名无效
+
+![doc](../img/FAQ/API域名无效.png)
+
+!!! Abstract ""
+    **API 域名内容说明**： 
+
+    - MaxKB 版本为 0.9.0，API 域名格式为：http://您ollama 所在服务的ip地址:您 ollama 的端口号 /v1 。 
+    - MaxKB 版本为 0.9.1及之后的版本 API 域名格式：http://您ollama 所在服务的ip地址:您 ollama 的端口号 / 。 
+
+    **注意：API 域名不可使用 127.0.0.1 或 localhost。**
+
+!!! Abstract ""
+    **获取 Ollama 服务的 IP 地址**：   
+    在 Ollama 所在服务器上执行: ip addr , 获取到服务器的 IP 地址。 查询 Ollama 服务器 IP 地址为 172.26.186.35，则 API 域名为：http://172.26.186.53:11434
+
+![doc](../img/FAQ/获取ipaddr.png){width="900px"}
+
+!!! Abstract ""
+    **确保服务可访问：**   
+    MaxKB 容器需要可正常访问 Ollama 服务。在 maxkb 容器中访问 Ollama 的 API 域名，确保返回 【Ollama is running 】的状态。
+
+![doc](../img/FAQ/ollama可访问.png){width="900px"}
+
+!!! Abstract ""
+    **Ollama 配置文件修改：**  
+    修改 /etc/systemd/system/ollama 文件，配置监听在 0.0.0.0 网段 增加 Environment=“OLLAMA_HOST=0.0.0.0” 。
+
+!!! Abstract ""
+    **以上确认无误后，再到 MaxKB 中 添加 Ollama 的模型。  
+    对于 Window 环境安装 Ollama 可进一步参考：[Windows 系统本地部署 Ollama +MaxKB 安装教程](https://kb.fit2cloud.com/?p=349d848b-7a0a-421b-8029-38e0440f35d4)。**
+
+
+
+### 2.2 对接图片生成模型时验证失败
+![doc](../img/FAQ/图片生成模型验证失败.png){width="900px"}
+
+!!! Abstract ""
+    原因是参数组件类型错误。具体表现为“guidance_scale”组件类型设置错误。解决方法是将“guidance_scale”组件类型更改为滑块，并将步长设置为 1。
+
+![doc](../img/FAQ/设置步长为1.png){width="900px"}
+
+### 2.3 对接 XInference 语音合成模型验证失败
+![doc](../img/FAQ/对接XInferenc语音模型失败.png)
+
+!!! Abstract ""
+    错误信息如下： Error code: 400 - {'detail': '[address=0.0.0.0:4215, pid=41292] Model not found, uid: XXX'} 。  
+    原因可能是模型名称或版本不正确。 解决步骤：  
+
+    - 检查模型名称：在容器中通过 curl 请求查看是否有对应的模型名称返回
+    - 检查 XInference 版本。当前使用的版本为 v1.3.0.post2，这是一个测试版本，可能存在不稳定的情况。建议切换到更稳定的版本，例如 XInference 的最新稳定版本。
+
+
+### 2.4 检查参数是否正确：Connection error
+
+!!! Abstract ""
+    这通常是由网络连接问题引起的。排查思路：  
+    
+    - 检查防火墙设置：确认防火墙是否限制了相关端口。如果限制了，请开放该端口，确保容器可以正常访问网络。
+
+    - 检查容器网络配置：确认容器内是否有网络连接。可以尝试在容器内执行网络测试命令（如 ping 或 curl）来检查网络连通性。

docs/img/FAQ/API域名无效.png

@@ -103,11 +103,14 @@ nav:
         - 开发环境搭建: dev_manual/dev_environment.md
         - 通过API KEY进行对话: dev_manual/APIKey_chat.md
     - 常见问题:
-        - Ollama离线部署LLM模型: faq/Offline_install_OllamaModel.md
-        - Ollama使用GPU运行LLM模型: faq/GPU_runOllama.md
-        - 将MaxKB小助手集成到Halo中: faq/maxkb_In_halo.md
-        - MaxKB和Dify有什么区别: faq/MaxKB VS.Dify.md
-        - 知识库文档如何合理分段: faq/doc_segment.md
+        - 安装部署: faq/install_configuration.md
+        - 系统管理: faq/system_management.md
+    - 实践教程:
+            - Ollama 离线部署 LLM 模型: faq/Offline_install_OllamaModel.md
+            - Ollama 使用 GPU 运行 LLM 模型: faq/GPU_runOllama.md
+            - 将 MaxKB 小助手集成到 Halo 中: faq/maxkb_In_halo.md
+            - MaxKB 和 Dify 有什么区别: faq/MaxKB VS.Dify.md
+            - 知识库文档如何合理分段: faq/doc_segment.md
     - 联系我们: contact.md
 
 markdown_extensions: