diff --git a/doc/docs/.vitepress/config.mts b/doc/docs/.vitepress/config.mts
index 6855a63f7..6ee76ff5d 100644
--- a/doc/docs/.vitepress/config.mts
+++ b/doc/docs/.vitepress/config.mts
@@ -60,10 +60,18 @@ export default defineConfig({
                 text: "Installation & Deployment",
                 link: "/en/quick-start/installation",
               },
+              {
+                text: "Kubernetes Installation & Deployment",
+                link: "/en/quick-start/kubernetes-installation",
+              },
               {
                 text: "Upgrade Guide",
                 link: "/en/quick-start/upgrade-guide",
               },
+              {
+                text: "Kubernetes Upgrade Guide",
+                link: "/en/quick-start/kubernetes-upgrade-guide",
+              },
               { text: "FAQ", link: "/en/quick-start/faq" },
             ],
           },
@@ -279,10 +287,18 @@ export default defineConfig({
             text: "快速开始",
             items: [
               { text: "安装部署", link: "/zh/quick-start/installation" },
+              {
+                text: "Kubernetes 安装与部署",
+                link: "/zh/quick-start/kubernetes-installation",
+              },
               {
                 text: "升级指导",
                 link: "/zh/quick-start/upgrade-guide",
               },
+              {
+                text: "Kubernetes 升级指南",
+                link: "/zh/quick-start/kubernetes-upgrade-guide",
+              },
               { text: "常见问题", link: "/zh/quick-start/faq" },
             ],
           },
diff --git a/doc/docs/en/quick-start/kubernetes-installation.md b/doc/docs/en/quick-start/kubernetes-installation.md
new file mode 100644
index 000000000..44ca3c993
--- /dev/null
+++ b/doc/docs/en/quick-start/kubernetes-installation.md
@@ -0,0 +1,216 @@
+# Kubernetes Installation & Deployment
+
+## 🎯 Prerequisites
+
+| Resource | Minimum | Recommended |
+|----------|---------|-------------|
+| **CPU**  | 4 cores | 8 cores |
+| **RAM**  | 16 GiB | 64 GiB |
+| **Disk** | 100 GiB | 200 GiB |
+| **Architecture** | x86_64 / ARM64 | x86_64 |
+| **Software** | Kubernetes 1.24+, Helm 3+, kubectl configured | Kubernetes 1.28+ |
+
+> **💡 Note**: The recommended configuration of **8 cores and 64 GiB RAM** provides optimal performance for production workloads.
+
+## 🚀 Quick Start
+
+### 1. Prepare Kubernetes Cluster
+
+Ensure your Kubernetes cluster is running and kubectl is configured with cluster access:
+
+```bash
+kubectl cluster-info
+kubectl get nodes
+```
+
+### 2. Clone and Navigate
+
+```bash
+git clone https://github.com/ModelEngine-Group/nexent.git
+cd nexent/k8s/helm
+```
+
+### 3. Deployment
+
+Run the deployment script:
+
+```bash
+./deploy-helm.sh apply
+```
+
+After executing this command, the system will prompt for configuration options:
+
+**Version Selection:**
+- **Speed version (Lightweight & Fast Deployment, Default)**: Quick startup of core features, suitable for individual users and small teams
+- **Full version (Complete Feature Edition)**: Provides enterprise-level tenant management and resource isolation features, includes Supabase authentication
+
+**Image Source Selection:**
+- **Mainland China**: Uses optimized regional mirrors for faster image pulling
+- **General**: Uses standard Docker Hub registries
+
+**Optional Components:**
+- **Terminal Tool**: Enables openssh-server for AI agent shell command execution
+
+### ⚠️ Important Notes
+
+1️⃣ **When deploying v1.8.0 or later for the first time**, you will be prompted to set a password for the `suadmin` super administrator account during the deployment process. This account has the highest system privileges. Please enter your desired password and **save it securely** after creation - it cannot be retrieved later.
+
+2️⃣ Forgot to note the `suadmin` account password? Follow these steps:
+
+```bash
+# Step 1: Delete su account record in Supabase database
+kubectl exec -it -n nexent deploy/nexent-supabase-db -- psql -U postgres -c \
+  "SELECT id, email FROM auth.users WHERE email='suadmin@nexent.com';"
+# Get the user_id and delete
+kubectl exec -it -n nexent deploy/nexent-supabase-db -- psql -U postgres -c \
+  "DELETE FROM auth.identities WHERE user_id='your_user_id';"
+kubectl exec -it -n nexent deploy/nexent-supabase-db -- psql -U postgres -c \
+  "DELETE FROM auth.users WHERE id='your_user_id';"
+
+# Step 2: Delete su account record in nexent database
+kubectl exec -it -n nexent deploy/nexent-postgresql -- psql -U root -d nexent -c \
+  "DELETE FROM nexent.user_tenant_t WHERE user_id='your_user_id';"
+
+# Step 3: Re-deploy and record the su account password
+./deploy-helm.sh apply
+```
+
+### 4. Access Your Installation
+
+When deployment completes successfully:
+
+| Service | Default Address |
+|---------|-----------------|
+| Web Application | http://localhost:30000 |
+| SSH Terminal | localhost:30022 (if enabled) |
+
+Access steps:
+1. Open **http://localhost:30000** in your browser
+2. Log in with the super administrator account
+3. Access tenant resources → Create tenant and tenant administrator
+4. Log in with the tenant administrator account
+5. Refer to the [User Guide](../user-guide/home-page) to develop agents
+
+## 🏗️ Service Architecture
+
+Nexent uses a microservices architecture deployed via Helm charts:
+
+**Application Services:**
+| Service | Description | Default Port |
+|---------|-------------|--------------|
+| nexent-config | Configuration service | 5010 |
+| nexent-runtime | Runtime service | 5010 |
+| nexent-mcp | MCP container service | 5010 |
+| nexent-northbound | Northbound API service | 5010 |
+| nexent-web | Web frontend | 3000 |
+| nexent-data-process | Data processing service | 5012 |
+
+**Infrastructure Services:**
+| Service | Description |
+|---------|-------------|
+| nexent-elasticsearch | Search and indexing engine |
+| nexent-postgresql | Relational database |
+| nexent-redis | Caching layer |
+| nexent-minio | S3-compatible object storage |
+
+**Supabase Services (Full Version Only):**
+| Service | Description |
+|---------|-------------|
+| nexent-supabase-kong | API Gateway |
+| nexent-supabase-auth | Authentication service |
+| nexent-supabase-db | Database service |
+
+**Optional Services:**
+| Service | Description |
+|---------|-------------|
+| nexent-openssh-server | SSH terminal for AI agents |
+
+## 🔌 Port Mapping
+
+| Service | Internal Port | NodePort | Description |
+|---------|---------------|----------|-------------|
+| Web Interface | 3000 | 30000 | Main application access |
+| Northbound API | 5010 | 30013 | Northbound API service |
+| SSH Server | 22 | 30022 | Terminal tool access |
+
+For internal service communication, services use Kubernetes internal DNS (e.g., `http://nexent-config:5010`).
+
+## 💾 Data Persistence
+
+Nexent uses PersistentVolumes for data persistence:
+
+| Data Type | PersistentVolume | Default Host Path |
+|-----------|------------------|-------------------|
+| Elasticsearch | nexent-elasticsearch-pv | `{dataDir}/elasticsearch` |
+| PostgreSQL | nexent-postgresql-pv | `{dataDir}/postgresql` |
+| Redis | nexent-redis-pv | `{dataDir}/redis` |
+| MinIO | nexent-minio-pv | `{dataDir}/minio` |
+| Supabase DB (Full) | nexent-supabase-db-pv | `{dataDir}/supabase-db` |
+
+Default `dataDir` is `/var/lib/nexent-data` (configurable in `values.yaml`).
+
+## 🔧 Deployment Commands
+
+```bash
+# Deploy with interactive prompts
+./deploy-helm.sh apply
+
+# Deploy with mainland China image sources
+./deploy-helm.sh apply --is-mainland Y
+
+# Deploy full version (with Supabase)
+./deploy-helm.sh apply --deployment-version full
+
+# Clean helm state only (fixes stuck releases)
+./deploy-helm.sh clean
+
+# Uninstall but preserve data
+./deploy-helm.sh delete
+
+# Complete uninstall including all data
+./deploy-helm.sh delete-all
+```
+
+## 🔍 Troubleshooting
+
+### Check Pod Status
+
+```bash
+kubectl get pods -n nexent
+kubectl describe pod <pod-name> -n nexent
+```
+
+### View Logs
+
+```bash
+kubectl logs -n nexent -l app=nexent-config
+kubectl logs -n nexent -l app=nexent-web
+kubectl logs -n nexent -l app=nexent-elasticsearch
+```
+
+### Restart Services
+
+```bash
+kubectl rollout restart deployment/nexent-config -n nexent
+kubectl rollout restart deployment/nexent-runtime -n nexent
+```
+
+### Re-initialize Elasticsearch
+
+If Elasticsearch initialization failed:
+
+```bash
+bash init-elasticsearch.sh
+```
+
+### Clean Up Stale PersistentVolumes
+
+```bash
+kubectl delete pv nexent-elasticsearch-pv nexent-postgresql-pv nexent-redis-pv nexent-minio-pv
+```
+
+## 💡 Need Help
+
+- Browse the [FAQ](./faq) for common install issues
+- Drop questions in our [Discord community](https://discord.gg/tb5H3S3wyv)
+- File bugs or feature ideas in [GitHub Issues](https://github.com/ModelEngine-Group/nexent/issues)
diff --git a/doc/docs/en/quick-start/kubernetes-upgrade-guide.md b/doc/docs/en/quick-start/kubernetes-upgrade-guide.md
new file mode 100644
index 000000000..293358d2f
--- /dev/null
+++ b/doc/docs/en/quick-start/kubernetes-upgrade-guide.md
@@ -0,0 +1,180 @@
+# Nexent Kubernetes Upgrade Guide
+
+## 🚀 Upgrade Overview
+
+Follow these steps to upgrade Nexent on Kubernetes safely:
+
+1. Pull the latest code
+2. Execute the Helm deployment script
+3. Open the site to confirm service availability
+
+---
+
+## 🔄 Step 1: Update Code
+
+Before updating, record the current deployment version and data directory information.
+
+- Current Deployment Version Location: `APP_VERSION` in `backend/consts/const.py`
+- Data Directory Location: `global.dataDir` in `k8s/helm/nexent/values.yaml`
+
+**Code downloaded via git**
+
+Update the code using git commands:
+
+```bash
+git pull
+```
+
+**Code downloaded via ZIP package or other means**
+
+1. Re-download the latest code from GitHub and extract it.
+2. Copy the `.deploy.options` file from the `k8s/helm` directory of your previous deployment to the new code directory. (If the file doesn't exist, you can ignore this step).
+
+## 🔄 Step 2: Execute the Upgrade
+
+Navigate to the k8s/helm directory of the updated code and run the deployment script:
+
+```bash
+cd k8s/helm
+./deploy-helm.sh apply
+```
+
+The script will detect your previous deployment settings (version, image source, etc.) from the `.deploy.options` file. If the file is missing, you will be prompted to enter configuration details.
+
+> 💡 Tip
+> If you need to configure voice models (STT/TTS), please edit the corresponding values in `values.yaml` or pass them via command line.
+
+---
+
+## 🌐 Step 3: Verify the Deployment
+
+After deployment:
+
+1. Open `http://localhost:30000` in your browser.
+2. Review the [User Guide](../user-guide/home-page) to validate agent functionality.
+
+---
+
+## 🗄️ Manual Database Update
+
+If some SQL files fail to execute during the upgrade, or if you need to run incremental SQL scripts manually, you can perform the update using the methods below.
+
+### 📋 Find SQL Scripts
+
+SQL migration scripts are located in the repository at:
+
+```
+docker/sql/
+```
+
+Check the [upgrade-guide](./upgrade-guide.md) or release notes to identify which SQL scripts need to be executed for your upgrade path.
+
+### ✅ Method A: Use a SQL Editor (recommended)
+
+1. Open your SQL client and create a new PostgreSQL connection.
+2. Get connection settings from the running PostgreSQL pod:
+
+   ```bash
+   # Get PostgreSQL pod name
+   kubectl get pods -n nexent -l app=nexent-postgresql
+
+   # Port-forward to access PostgreSQL locally
+   kubectl port-forward svc/nexent-postgresql 5433:5432 -n nexent &
+   ```
+
+3. Connection details:
+   - Host: `localhost`
+   - Port: `5433` (forwarded port)
+   - Database: `nexent`
+   - User: `root`
+   - Password: Check in `k8s/helm/nexent/charts/nexent-common/values.yaml`
+
+4. Test the connection. When successful, you should see tables under the `nexent` schema.
+5. Execute the required SQL file(s) in version order.
+
+> ⚠️ Important
+> - Always back up the database first, especially in production.
+> - Run scripts sequentially to avoid dependency issues.
+
+### 🧰 Method B: Use kubectl exec (no SQL client required)
+
+Execute SQL scripts directly via stdin redirection:
+
+1. Get the PostgreSQL pod name:
+
+   ```bash
+   kubectl get pods -n nexent -l app=nexent-postgresql -o jsonpath='{.items[0].metadata.name}'
+   ```
+
+2. Execute the SQL file directly from your host machine:
+
+   ```bash
+   kubectl exec -i <pod-name> -n nexent -- psql -U root -d nexent < ./sql/v1.1.1_1030-update.sql
+   ```
+
+   Or if you want to see the output interactively:
+
+   ```bash
+   cat ./sql/v1.1.1_1030-update.sql | kubectl exec -i <pod-name> -n nexent -- psql -U root -d nexent
+   ```
+
+**Example - Execute multiple SQL files:**
+
+```bash
+# Get PostgreSQL pod name
+POSTGRES_POD=$(kubectl get pods -n nexent -l app=nexent-postgresql -o jsonpath='{.items[0].metadata.name}')
+
+# Execute SQL files in order
+kubectl exec -i $POSTGRES_POD -n nexent -- psql -U root -d nexent < ./sql/v1.8.0_xxxxx-update.sql
+kubectl exec -i $POSTGRES_POD -n nexent -- psql -U root -d nexent < ./sql/v2.0.0_0314_add_context_skill_t.sql
+```
+
+> 💡 Tips
+> - Create a backup before running migrations:
+
+   ```bash
+   POSTGRES_POD=$(kubectl get pods -n nexent -l app=nexent-postgresql -o jsonpath='{.items[0].metadata.name}')
+   kubectl exec nexent/$POSTGRES_POD -n nexent -- pg_dump -U root nexent > backup_$(date +%F).sql
+   ```
+
+> - For Supabase database (full version only), use `nexent-supabase-db` pod instead:
+
+   ```bash
+   SUPABASE_POD=$(kubectl get pods -n nexent -l app=nexent-supabase-db -o jsonpath='{.items[0].metadata.name}')
+   kubectl cp docker/sql/xxx.sql nexent/$SUPABASE_POD:/tmp/update.sql
+   kubectl exec -it nexent/$SUPABASE_POD -n nexent -- psql -U postgres -f /tmp/update.sql
+   ```
+
+---
+
+## 🔍 Troubleshooting
+
+### Check Deployment Status
+
+```bash
+kubectl get pods -n nexent
+kubectl rollout status deployment/nexent-config -n nexent
+```
+
+### View Logs
+
+```bash
+kubectl logs -n nexent -l app=nexent-config --tail=100
+kubectl logs -n nexent -l app=nexent-web --tail=100
+```
+
+### Restart Services After Manual SQL Update（if needed）
+
+If you executed SQL scripts manually, restart the affected services:
+
+```bash
+kubectl rollout restart deployment/nexent-config -n nexent
+kubectl rollout restart deployment/nexent-runtime -n nexent
+```
+
+### Re-initialize Elasticsearch (if needed)
+
+```bash
+cd k8s/helm
+bash init-elasticsearch.sh
+```
diff --git a/doc/docs/zh/quick-start/kubernetes-installation.md b/doc/docs/zh/quick-start/kubernetes-installation.md
new file mode 100644
index 000000000..be7857fb2
--- /dev/null
+++ b/doc/docs/zh/quick-start/kubernetes-installation.md
@@ -0,0 +1,216 @@
+# Kubernetes 安装部署
+
+## 🎯 系统要求
+
+| 资源 | 最低要求 | 推荐配置 |
+|----------|---------|-------------|
+| **CPU**  | 4 核 | 8 核 |
+| **内存**  | 16 GiB | 64 GiB |
+| **磁盘** | 100 GiB | 200 GiB |
+| **架构** | x86_64 / ARM64 |
+| **软件** | Kubernetes 1.24+, Helm 3+, kubectl 已配置 | Kubernetes 1.28+ |
+
+> **💡 注意**：推荐的 **8 核 64 GiB 内存** 配置可确保生产环境下的最佳性能。
+
+## 🚀 快速开始
+
+### 1. 准备 Kubernetes 集群
+
+确保 Kubernetes 集群正常运行，且 kubectl 已配置好集群访问权限：
+
+```bash
+kubectl cluster-info
+kubectl get nodes
+```
+
+### 2. 克隆并进入目录
+
+```bash
+git clone https://github.com/ModelEngine-Group/nexent.git
+cd nexent/k8s/helm
+```
+
+### 3. 部署
+
+运行部署脚本：
+
+```bash
+./deploy-helm.sh apply
+```
+
+执行此命令后，系统会提示您选择配置选项：
+
+**版本选择:**
+- **Speed version（轻量快速部署，默认）**: 快速启动核心功能，适合个人用户和小团队使用
+- **Full version（完整功能版）**: 提供企业级租户管理和资源隔离等高级功能，包含 Supabase 认证服务
+
+**镜像源选择:**
+- **中国大陆**: 使用优化的区域镜像源，加快镜像拉取速度
+- **通用**: 使用标准 Docker Hub 镜像源
+
+**可选组件:**
+- **终端工具**: 启用 openssh-server 供 AI 智能体执行 shell 命令
+
+### ⚠️ 重要提示
+
+1️⃣ **首次部署 v1.8.0 及以上版本时**，部署过程中系统会提示您设置 `suadmin` 超级管理员账号的密码。该账号为系统最高权限账户，请输入您想要的密码并**妥善保存**——密码创建后无法再次找回。
+
+2️⃣ 忘记记录 `suadmin` 账号密码？请按照以下步骤操作：
+
+```bash
+# Step 1: 在 Supabase 数据库中删除 su 账号记录
+kubectl exec -it -n nexent deploy/nexent-supabase-db -- psql -U postgres -c \
+  "SELECT id, email FROM auth.users WHERE email='suadmin@nexent.com';"
+# 获取 user_id 后执行删除
+kubectl exec -it -n nexent deploy/nexent-supabase-db -- psql -U postgres -c \
+  "DELETE FROM auth.identities WHERE user_id='your_user_id';"
+kubectl exec -it -n nexent deploy/nexent-supabase-db -- psql -U postgres -c \
+  "DELETE FROM auth.users WHERE id='your_user_id';"
+
+# Step 2: 在 nexent 数据库中删除 su 账号记录
+kubectl exec -it -n nexent deploy/nexent-postgresql -- psql -U root -d nexent -c \
+  "DELETE FROM nexent.user_tenant_t WHERE user_id='your_user_id';"
+
+# Step 3: 重新部署并记录 su 账号密码
+./deploy-helm.sh apply
+```
+
+### 4. 访问您的安装
+
+部署成功完成后：
+
+| 服务 | 默认地址 |
+|---------|-----------------|
+| Web 应用 | http://localhost:30000 |
+| SSH 终端 | localhost:30022（已启用时） |
+
+访问步骤：
+1. 在浏览器中打开 **http://localhost:30000**
+2. 登录超级管理员账号
+3. 访问租户资源 → 创建租户及租户管理员
+4. 登录租户管理员账号
+5. 参考 [用户指南](../user-guide/home-page) 进行智能体的开发
+
+## 🏗️ 服务架构
+
+Nexent 采用微服务架构，通过 Helm Chart 进行部署：
+
+**应用服务:**
+| 服务 | 描述 | 默认端口 |
+|---------|-------------|--------------|
+| nexent-config | 配置服务 | 5010 |
+| nexent-runtime | 运行时服务 | 5014 |
+| nexent-mcp | MCP 容器服务 | 5011 |
+| nexent-northbound | 北向 API 服务 | 5013 |
+| nexent-web | Web 前端 | 3000 |
+| nexent-data-process | 数据处理服务 | 5012 |
+
+**基础设施服务:**
+| 服务 | 描述 |
+|---------|-------------|
+| nexent-elasticsearch | 搜索引擎和索引服务 |
+| nexent-postgresql | 关系型数据库 |
+| nexent-redis | 缓存层 |
+| nexent-minio | S3 兼容对象存储 |
+
+**Supabase 服务（完整版独有）:**
+| 服务 | 描述 |
+|---------|-------------|
+| nexent-supabase-kong | API 网关 |
+| nexent-supabase-auth | 认证服务 |
+| nexent-supabase-db | 数据库服务 |
+
+**可选服务:**
+| 服务 | 描述 |
+|---------|-------------|
+| nexent-openssh-server | AI 智能体 SSH 终端 |
+
+## 🔌 端口映射
+
+| 服务 | 内部端口 | NodePort | 描述 |
+|---------|---------------|----------|-------------|
+| Web 界面 | 3000 | 30000 | 主应用程序访问 |
+| Northbound API | 5010 | 30013 | 北向 API 服务 |
+| SSH 服务器 | 22 | 30022 | 终端工具访问 |
+
+内部服务通信使用 Kubernetes 内部 DNS（例如 `http://nexent-config:5010`）。
+
+## 💾 数据持久化
+
+Nexent 使用 PersistentVolume 进行数据持久化：
+
+| 数据类型 | PersistentVolume | 默认宿主机路径 |
+|-----------|------------------|-------------------|
+| Elasticsearch | nexent-elasticsearch-pv | `{dataDir}/elasticsearch` |
+| PostgreSQL | nexent-postgresql-pv | `{dataDir}/postgresql` |
+| Redis | nexent-redis-pv | `{dataDir}/redis` |
+| MinIO | nexent-minio-pv | `{dataDir}/minio` |
+| Supabase DB（完整版）| nexent-supabase-db-pv | `{dataDir}/supabase-db` |
+
+默认 `dataDir` 为 `/var/lib/nexent-data`（可在 `values.yaml` 中配置）。
+
+## 🔧 部署命令
+
+```bash
+# 交互式部署
+./deploy-helm.sh apply
+
+# 使用中国大陆镜像源部署
+./deploy-helm.sh apply --is-mainland Y
+
+# 部署完整版本（包含 Supabase）
+./deploy-helm.sh apply --deployment-version full
+
+# 仅清理 Helm 状态（修复卡住的发布）
+./deploy-helm.sh clean
+
+# 卸载但保留数据
+./deploy-helm.sh delete
+
+# 完全卸载包括所有数据
+./deploy-helm.sh delete-all
+```
+
+## 🔍 故障排查
+
+### 查看 Pod 状态
+
+```bash
+kubectl get pods -n nexent
+kubectl describe pod <pod-name> -n nexent
+```
+
+### 查看日志
+
+```bash
+kubectl logs -n nexent -l app=nexent-config
+kubectl logs -n nexent -l app=nexent-web
+kubectl logs -n nexent -l app=nexent-elasticsearch
+```
+
+### 重启服务
+
+```bash
+kubectl rollout restart deployment/nexent-config -n nexent
+kubectl rollout restart deployment/nexent-runtime -n nexent
+```
+
+### 重新初始化 Elasticsearch
+
+如果 Elasticsearch 初始化失败：
+
+```bash
+bash init-elasticsearch.sh
+```
+
+### 清理过期的 PersistentVolume
+
+```bash
+kubectl delete pv nexent-elasticsearch-pv nexent-postgresql-pv nexent-redis-pv nexent-minio-pv
+```
+
+## 💡 需要帮助
+
+- 浏览 [常见问题](./faq) 了解常见安装问题
+- 在我们的 [Discord 社区](https://discord.gg/tb5H3S3wyv) 提问
+- 在 [GitHub Issues](https://github.com/ModelEngine-Group/nexent/issues) 中提交错误报告或功能建议
diff --git a/doc/docs/zh/quick-start/kubernetes-upgrade-guide.md b/doc/docs/zh/quick-start/kubernetes-upgrade-guide.md
new file mode 100644
index 000000000..43f5c1d49
--- /dev/null
+++ b/doc/docs/zh/quick-start/kubernetes-upgrade-guide.md
@@ -0,0 +1,180 @@
+# Nexent Kubernetes 升级指导
+
+## 🚀 升级流程概览
+
+在 Kubernetes 上升级 Nexent 时，建议依次完成以下几个步骤：
+
+1. 拉取最新代码
+2. 执行 Helm 部署脚本
+3. 打开站点确认服务可用
+
+---
+
+## 🔄 步骤一：更新代码
+
+更新之前，先记录下当前部署的版本和数据目录信息。
+
+- 当前部署版本信息的位置：`backend/consts/const.py` 中的 `APP_VERSION`
+- 数据目录信息的位置：`k8s/helm/nexent/values.yaml` 中的 `global.dataDir`
+
+**git 方式下载的代码**
+
+通过 git 指令更新代码：
+
+```bash
+git pull
+```
+
+**zip 包等方式下载的代码**
+
+1. 需要去 GitHub 上重新下载一份最新代码，并解压缩。
+2. 将之前执行部署脚本目录下 `k8s/helm` 目录中的 `.deploy.options` 文件拷贝到新代码目录的 `k8s/helm` 目录中。（如果不存在该文件则忽略此步骤）。
+
+## 🔄 步骤二：执行升级
+
+进入更新后代码目录的 `k8s/helm` 目录，执行部署脚本：
+
+```bash
+cd k8s/helm
+./deploy-helm.sh apply
+```
+
+脚本会自动检测您之前的部署设置（版本、镜像源等）。如果 `.deploy.options` 文件不存在，系统会提示您输入配置信息。
+
+> 💡 提示
+> - 若需配置语音模型（STT/TTS），请在对应的 `values.yaml` 中修改相关配置，或通过命令行参数传入。
+
+---
+
+## 🌐 步骤三：验证部署
+
+部署完成后：
+
+1. 在浏览器打开 `http://localhost:30000`
+2. 参考 [用户指南](../user-guide/home-page) 完成智能体配置与验证
+
+---
+
+## 🗄️ 手动更新数据库
+
+升级时如果存在部分 SQL 文件执行失败，或需要手动执行增量 SQL 脚本时，可以通过以下方法进行更新。
+
+### 📋 查找 SQL 脚本
+
+SQL 迁移脚本位于仓库的：
+
+```
+docker/sql/
+```
+
+请查看 [升级指南](./upgrade-guide.md) 或版本发布说明，确认需要执行哪些 SQL 脚本。
+
+### ✅ 方法一：使用 SQL 编辑器（推荐）
+
+1. 打开 SQL 编辑器，新建 PostgreSQL 连接。
+2. 从正在运行的 PostgreSQL Pod 中获取连接信息：
+
+   ```bash
+   # 获取 PostgreSQL Pod 名称
+   kubectl get pods -n nexent -l app=nexent-postgresql
+
+   # 端口转发以便本地访问 PostgreSQL
+   kubectl port-forward svc/nexent-postgresql 5433:5432 -n nexent &
+   ```
+
+3. 连接信息：
+   - Host: `localhost`
+   - Port: `5433`（转发的端口）
+   - Database: `nexent`
+   - User: `root`
+   - Password: 可在 `k8s/helm/nexent/charts/nexent-common/values.yaml` 中查看
+
+4. 填写连接信息后测试连接，确认成功后可在 `nexent` schema 中查看所有表。
+5. 按版本顺序执行所需的 SQL 文件。
+
+> ⚠️ 注意事项
+> - 升级前请备份数据库，生产环境尤为重要。
+> - SQL 脚本需按时间顺序执行，避免依赖冲突。
+
+### 🧰 方法二：使用 kubectl exec（无需客户端）
+
+通过 stdin 重定向直接在主机上执行 SQL 脚本：
+
+1. 获取 PostgreSQL Pod 名称：
+
+   ```bash
+   kubectl get pods -n nexent -l app=nexent-postgresql -o jsonpath='{.items[0].metadata.name}'
+   ```
+
+2. 直接从主机执行 SQL 文件：
+
+   ```bash
+   kubectl exec -i <pod-name> -n nexent -- psql -U root -d nexent < ./sql/v1.1.1_1030-update.sql
+   ```
+
+   或者如果想交互式查看输出：
+
+   ```bash
+   cat ./sql/v1.1.1_1030-update.sql | kubectl exec -i <pod-name> -n nexent -- psql -U root -d nexent
+   ```
+
+**示例 - 依次执行多个 SQL 文件：**
+
+```bash
+# 获取 PostgreSQL Pod 名称
+POSTGRES_POD=$(kubectl get pods -n nexent -l app=nexent-postgresql -o jsonpath='{.items[0].metadata.name}')
+
+# 按顺序执行 SQL 文件
+kubectl exec -i $POSTGRES_POD -n nexent -- psql -U root -d nexent < ./sql/v1.8.0_xxxxx-update.sql
+kubectl exec -i $POSTGRES_POD -n nexent -- psql -U root -d nexent < ./sql/v2.0.0_0314_add_context_skill_t.sql
+```
+
+> 💡 提示
+> - 执行前建议先备份数据库：
+
+   ```bash
+   POSTGRES_POD=$(kubectl get pods -n nexent -l app=nexent-postgresql -o jsonpath='{.items[0].metadata.name}')
+   kubectl exec nexent/$POSTGRES_POD -n nexent -- pg_dump -U root nexent > backup_$(date +%F).sql
+   ```
+
+> - 对于 Supabase 数据库（仅完整版本），请使用 `nexent-supabase-db` Pod：
+
+   ```bash
+   SUPABASE_POD=$(kubectl get pods -n nexent -l app=nexent-supabase-db -o jsonpath='{.items[0].metadata.name}')
+   kubectl cp docker/sql/xxx.sql nexent/$SUPABASE_POD:/tmp/update.sql
+   kubectl exec -it nexent/$SUPABASE_POD -n nexent -- psql -U postgres -f /tmp/update.sql
+   ```
+
+---
+
+## 🔍 故障排查
+
+### 查看部署状态
+
+```bash
+kubectl get pods -n nexent
+kubectl rollout status deployment/nexent-config -n nexent
+```
+
+### 查看日志
+
+```bash
+kubectl logs -n nexent -l app=nexent-config --tail=100
+kubectl logs -n nexent -l app=nexent-web --tail=100
+```
+
+### 手动 SQL 更新后重启服务（如需要）
+
+如果您手动执行了 SQL 脚本，需要重启受影响的服务：
+
+```bash
+kubectl rollout restart deployment/nexent-config -n nexent
+kubectl rollout restart deployment/nexent-runtime -n nexent
+```
+
+### 重新初始化 Elasticsearch（如需要）
+
+```bash
+cd k8s/helm
+bash init-elasticsearch.sh
+```