update readme

README.md

@@ -67,7 +67,6 @@ Astron-xmod-shim 采用“核心引擎 + 双插件”的解耦架构，通过抽
 - Go 1.24+（开发环境）
 - 目标环境（如 K8s v1.19+，如需使用 K8s shimlet）
 
-
 ### Helm部署
 
 Astron-xmod-shim 也提供了 Helm Chart 部署方式，适用于 Kubernetes 环境。
@@ -77,6 +76,7 @@ Astron-xmod-shim 也提供了 Helm Chart 部署方式，适用于 Kubernetes 环
 - 已安装 Helm 3.x
 - 已配置 kubectl 连接到目标 Kubernetes 集群
 - 主机上已存在配置目录和模型目录
+- [关于模型目录挂载的详细说明](deploy/docs/filesystem.md)
 
 #### 部署命令
 
@@ -122,6 +122,7 @@ helm uninstall astron-xmod-shim
 ```
 
 ## API 参考文档
+
 [API参考文档](deploy/docs/api.md)
 
 ## 插件开发指南
@@ -132,12 +133,13 @@ Shimlet 负责将抽象的部署请求转换为具体环境的操作。以下是
 
 #### 内置示例：Kubernetes Shimlet
 
-Astron-xmod-shim 原生内置了 Kubernetes Shimlet，用于在 Kubernetes 环境中部署模型服务。它实现了标准的 Shimlet 接口，能够将抽象部署请求转换为
+Astron-xmod-shim 原生内置了 Kubernetes Shimlet，用于在 Kubernetes 环境中部署模型服务。它实现了标准的 Shimlet
+接口，能够将抽象部署请求转换为
 Kubernetes 的资源操作（如创建 Deployment 和 Service 等）。
 
 #### 扩展示例：Docker Shimlet 实现
-[自定义Shimlet示例](deploy/docs/shimlet-demo.md)
 
+[自定义Shimlet示例](deploy/docs/shimlet-demo.md)
 
 ### 预定义收敛目标集合（GoalSet）
 
@@ -148,7 +150,6 @@ GoalSet 定义了模型部署的具体目标和执行逻辑。Astron-xmod-shim 
 Astron-xmod-shim 原生内置了 OpenSourceLLM GoalSet，用于开源大模型的部署流程。它采用 Builder
 模式实现，包含模型路径映射、部署完成验证、规格一致性检查和服务暴露等关键目标，使用户能够快速部署开源大模型服务。
 
-
 ### 扩展示例：业务场景 GoalSet
 
 开发者可以根据具体业务需求创建专用的GoalSet。例如：
@@ -159,13 +160,11 @@ Astron-xmod-shim 原生内置了 OpenSourceLLM GoalSet，用于开源大模型
 
 [自定义GoalSet示例](deploy/docs/goalset-demo.md)
 
-
 ## 配置文件结构说明
 
 Astron-xmod-shim 支持通过命令行参数和配置文件进行配置：
 [配置文件整体说明](deploy/docs/conf.md)
 
-
 ## 贡献指南
 
 我们欢迎社区贡献，贡献前请阅读以下指南：
@@ -178,8 +177,7 @@ Astron-xmod-shim 支持通过命令行参数和配置文件进行配置：
 ## 🌟 Star 历史
 
 <div align="center">
-  <img src="https://api.star-history.com/svg?repos=iflytek/Astron-xmod-shim
-&type=Date" alt="Star History Chart" width="600">
+  <img src="https://api.star-history.com/svg?repos=iflytek/Astron-xmod-shim&type=Date" alt="Star History Chart" width="600">
 </div>
 
 ## 许可证

deploy/docs/conf.md

@@ -1,9 +1,26 @@
-## 项目文件结构
+## Astron-xmod-shim 配置文件结构说明
 
+Astron-xmod-shim 采用分层配置管理机制，配置文件主要集中在 conf/ 目录下，按照功能和插件类型进行分类存放。以下是项目的配置文件结构及其各文件的含义和归属：
 
 conf/
 ├── base/
-│   └── conf.yaml         # 核心配置文件
+│ └── conf.yaml # 核心配置文件
 └── shimlets/
-    ├── k8s-shimlet.yaml  # Kubernetes shimlet 配置
-    └── kubeconfig        # Kubernetes 集群连接配置
+├── k8s-shimlet.yaml # Kubernetes shimlet 配置
+└── kubeconfig # Kubernetes 集群连接配置
+
+## 各配置文件详细说明
+
+1. 核心配置文件 (conf/base/conf.yaml)
+   归属：系统级核心配置，由主程序直接加载和解析。
+
+   主要功能：定义整个应用的基础配置参数，包括Kubernetes客户端、HTTP服务器、日志系统、当前激活的shimlet、各shimlet插件的配置路径、模型管理和跟踪器等核心组件的配置。
+
+2. Shimlet配置文件 (conf/shimlets/k8s-shimlet.yaml)
+   归属：Kubernetes shimlet插件专用配置文件。
+
+主要功能：定义内置的 Kubernetes shimlet插件的特定配置参数，用于对接Kubernetes集群。
+
+## 配置扩展性
+
+从配置结构可以看出，项目采用了模块化设计，支持多种shimlet插件的扩展。新的shimlet插件可以通过在conf/base/conf.yaml的shimlets部分注册，并提供对应的配置文件路径来实现集成。

deploy/docs/filesystem.md

@@ -0,0 +1,79 @@
+# 模型目录挂载说明
+
+
+Astron-xmod-shim 采用共享存储模式挂载模型目录，具体特点如下：
+
+- 主机上的模型目录直接挂载至推理服务 Pod。
+- 控制平面与推理服务使用相同的模型目录路径。
+- 无需额外的文件复制或同步操作。
+
+该设计避免了模型文件的冗余存储，提升了访问效率。
+
+## 实现方式
+
+### 系统级挂载（控制平面）
+
+Astron-xmod-shim 作为控制平面，通过 Helm Chart 配置将主机目录挂载到容器中。示例如下：
+
+```yaml
+# values.yaml
+volumes:
+  - name: maasmodels-volume
+    hostPath:
+      path: /mnt/maasmodels/
+      type: Directory
+
+volumeMounts:
+  - name: maasmodels-volume
+    mountPath: /mnt/maasmodels/
+    readOnly: true
+```
+
+### 推理服务挂载（推理 Pod）
+
+创建推理服务时，系统自动为每个 Pod 配置相同的 HostPath 挂载：
+
+```go
+spec.WithVolumes(
+    corev1apply.Volume().
+        WithName("models").
+        WithHostPath(
+            corev1apply.HostPathVolumeSource().
+                WithPath(modelDirPath),
+                WithType(corev1.HostPathDirectory),
+        ),
+)
+
+container.WithVolumeMounts(
+    corev1apply.VolumeMount().
+        WithName("models").
+        WithMountPath(modelDirPath),
+)
+
+container.WithArgs(
+    "--host=0.0.0.0",
+    "--port="+portStr,
+    "--model="+modelDirPath,
+)
+```
+
+## 关键要求
+
+- 主机路径与容器内挂载路径必须完全一致。
+- 模型文件直接从主机读取，无需同步。
+- 使用 HostPath 实现低开销、高性能的文件访问。
+- 模型路径只需在 Helm 配置中定义一次，系统自动应用于推理服务。
+
+## 修改默认路径的注意事项
+
+默认模型目录为 `/mnt/maasmodels/`。如需修改，必须同时满足以下条件：
+
+1. 更新 Helm `values.yaml` 中的 `volumes.hostPath.path` 和 `volumeMounts.mountPath`。
+2. 确保集群所有节点在指定路径下存在相同的模型文件。
+3. 推理服务启动参数 `--model` 的值必须与挂载路径一致。
+
+## 常见问题
+
+- **模型加载失败**：检查主机路径是否存在，目录结构是否正确。
+- **权限错误**：确认容器运行用户对模型目录具有读取权限。
+- **多节点不一致**：HostPath 仅挂载本地节点目录，多节点部署时需保证各节点模型文件同步。