Skip to content

Commit 3bef4a3

Browse files
WMC001WMC001
committed
📝 Update upgrade guide doc
1 parent a45e57e commit 3bef4a3

File tree

3 files changed

+246
-0
lines changed

3 files changed

+246
-0
lines changed

‎doc/docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@ export default defineConfig({
150150
items: [
151151
{ text: "Docker Build", link: "/en/deployment/docker-build" },
152152
{ text: "Dev Container", link: "/en/deployment/devcontainer" },
153+
{ text: "Upgrade Guide", link: "/en/deployment/upgrade-guide" },
153154
],
154155
},
155156
{
@@ -309,6 +310,7 @@ export default defineConfig({
309310
items: [
310311
{ text: "Docker 构建", link: "/zh/deployment/docker-build" },
311312
{ text: "开发容器", link: "/zh/deployment/devcontainer" },
313+
{ text: "升级指导", link: "/zh/deployment/upgrade-guide" },
312314
],
313315
},
314316
{

‎doc/docs/en/deployment/upgrade-guide.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Nexent Upgrade Guide
2+
3+
## 🚀 Upgrade Overview
4+
5+
Follow these four steps to upgrade Nexent safely:
6+
7+
1. Clean up existing containers and images
8+
2. Pull the latest code and run the deployment script
9+
3. Apply database migrations
10+
4. Verify the deployment in your browser
11+
12+
---
13+
14+
## 🧹 Step 1: Clean up old images
15+
16+
Remove cached resources to avoid conflicts when redeploying:
17+
18+
```bash
19+
# Stop and remove existing containers
20+
docker compose down
21+
22+
# Inspect and remove Nexent images
23+
docker images | grep nexent
24+
docker images | grep nexent | awk '{print $3}' | xargs docker rmi -f
25+
26+
# (Optional) prune unused images and caches
27+
docker system prune -af
28+
```
29+
30+
> ⚠️ Notes
31+
> - Back up critical data before deleting images.
32+
> - To preserve database data, do not delete the mounted database volume (`/nexent/docker/volumes` or your custom path).
33+
34+
---
35+
36+
## 🔄 Step 2: Update code and redeploy
37+
38+
```bash
39+
git pull
40+
cd nexent/docker
41+
cp .env.example .env
42+
bash deploy.sh
43+
```
44+
45+
> 💡 Tip
46+
> - `.env.example` works for default deployments.
47+
> - Configure speech models (STT/TTS) in `.env` when needed. A frontend configuration flow is coming soon.
48+
49+
---
50+
51+
## 🗄️ Step 3: Apply database migrations
52+
53+
Run the SQL scripts shipped with each release to keep your schema up to date.
54+
55+
### ✅ Method A: Use a SQL editor (recommended)
56+
57+
1. Open your SQL client and create a new PostgreSQL connection.
58+
2. Retrieve connection settings from `/nexent/docker/.env`:
59+
- Host
60+
- Port
61+
- Database
62+
- User
63+
- Password
64+
3. Test the connection. When successful, you should see tables under the `nexent` schema.
65+
4. Open a new query window.
66+
5. Navigate to `/nexent/docker/sql`. Each file contains one migration script with its release date in the filename.
67+
6. Execute every script dated after your previous deployment, in chronological order.
68+
69+
> ⚠️ Important
70+
> - Always back up the database first, especially in production.
71+
> - Run scripts sequentially to avoid dependency issues.
72+
> - `.env` keys may be named `POSTGRES_HOST`, `POSTGRES_PORT`, and so on—map them accordingly in your SQL client.
73+
74+
### 🧰 Method B: Use the command line (no SQL client required)
75+
76+
1. Switch to the Docker directory:
77+
78+
```bash
79+
cd nexent/docker
80+
```
81+
82+
2. Read database connection details from `.env`, for example:
83+
84+
```bash
85+
POSTGRES_HOST=localhost
86+
POSTGRES_PORT=5432
87+
POSTGRES_DB=nexent
88+
POSTGRES_USER=postgres
89+
POSTGRES_PASSWORD=your_password
90+
```
91+
92+
3. Execute SQL files sequentially (host machine example):
93+
94+
```bash
95+
docker exec -i nexent-postgresql psql -U $POSTGRES_USER -d $POSTGRES_DB < ./sql/2025-10-30-update.sql
96+
docker exec -i nexent-postgresql psql -U $POSTGRES_USER -d $POSTGRES_DB < ./sql/2025-11-05-update.sql
97+
```
98+
99+
Replace the filenames with the migrations released after your last deployment.
100+
101+
> 💡 Tips
102+
> - Load environment variables first if they are defined in `.env`:
103+
>
104+
> ```bash
105+
> export $(grep -v '^#' .env | xargs)
106+
> ```
107+
>
108+
> - Create a backup before running migrations:
109+
>
110+
> ```bash
111+
> docker exec -i nexent-postgres pg_dump -U $POSTGRES_USER $POSTGRES_DB > backup_$(date +%F).sql
112+
> ```
113+
114+
---
115+
116+
## 🌐 Step 4: Verify the deployment
117+
118+
After deployment:
119+
120+
1. Open `http://localhost:3000` in your browser.
121+
2. Review the [User Guide](https://doc.nexent.tech/en/user-guide/) to validate agent functionality.
122+
123+

‎doc/docs/zh/deployment/upgrade-guide.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Nexent 升级指导
2+
3+
## 🚀 升级流程概览
4+
5+
升级 Nexent 时建议依次完成以下四个步骤：
6+
7+
1. 清理旧版本容器与镜像
8+
2. 拉取最新代码并执行部署脚本
9+
3. 同步数据库结构
10+
4. 打开站点确认服务可用
11+
12+
---
13+
14+
## 🧹 步骤一：清理旧版本镜像
15+
16+
为避免缓存或版本冲突，先清理旧容器与镜像：
17+
18+
```bash
19+
# 停止并删除现有容器
20+
docker compose down
21+
22+
# 查看并删除 Nexent 镜像
23+
docker images | grep nexent
24+
docker images | grep nexent | awk '{print $3}' | xargs docker rmi -f
25+
26+
# （可选）清理未使用的镜像与缓存
27+
docker system prune -af
28+
```
29+
30+
> ⚠️ 注意事项
31+
> - 删除镜像前请先备份重要数据。
32+
> - 若需保留数据库数据，请勿删除数据库 volume（通常位于 `/nexent/docker/volumes` 或自定义挂载路径）。
33+
34+
---
35+
36+
## 🔄 步骤二：更新代码并部署
37+
38+
```bash
39+
git pull
40+
cd nexent/docker
41+
cp .env.example .env
42+
bash deploy.sh
43+
```
44+
45+
> 💡 提示
46+
> - 默认为快速部署场景，可直接使用 `.env.example`。
47+
> - 若需配置语音模型（STT/TTS），请在 `.env` 中补充相关变量，我们将尽快提供前端配置入口。
48+
49+
---
50+
51+
## 🗄️ 步骤三：同步数据库
52+
53+
升级后需要执行数据库迁移脚本，使 schema 保持最新。
54+
55+
### ✅ 方法一：使用 SQL 编辑器（推荐）
56+
57+
1. 打开 SQL 编辑器，新建 PostgreSQL 连接。
58+
2. 在 `/nexent/docker/.env` 中找到以下信息：
59+
- Host
60+
- Port
61+
- Database
62+
- User
63+
- Password
64+
3. 填写连接信息后测试连接，确认成功后可在 `nexent` schema 中查看所有表。
65+
4. 新建查询窗口。
66+
5. 打开 `/nexent/docker/sql` 目录，按文件名中的日期顺序查看 SQL 脚本。
67+
6. 根据上次部署日期，依次执行之后的每个 SQL 文件。
68+
69+
> ⚠️ 注意事项
70+
> - 升版本前请备份数据库，生产环境尤为重要。
71+
> - SQL 脚本需按时间顺序执行，避免依赖冲突。
72+
> - `.env` 变量可能命名为 `POSTGRES_HOST`、`POSTGRES_PORT` 等，请在客户端对应填写。
73+
74+
### 🧰 方法二：命令行执行（无需客户端）
75+
76+
1. 进入 Docker 目录：
77+
78+
```bash
79+
cd nexent/docker
80+
```
81+
82+
2. 从 `.env` 中获取数据库连接信息，例如：
83+
84+
```bash
85+
POSTGRES_HOST=localhost
86+
POSTGRES_PORT=5432
87+
POSTGRES_DB=nexent
88+
POSTGRES_USER=postgres
89+
POSTGRES_PASSWORD=your_password
90+
```
91+
92+
3. 通过容器执行 SQL 脚本（示例）：
93+
94+
```bash
95+
docker exec -i nexent-postgresql psql -U $POSTGRES_USER -d $POSTGRES_DB < ./sql/2025-10-30-update.sql
96+
docker exec -i nexent-postgresql psql -U $POSTGRES_USER -d $POSTGRES_DB < ./sql/2025-11-05-update.sql
97+
```
98+
99+
请根据自己的部署时间，按时间顺序执行对应脚本。
100+
101+
> 💡 提示
102+
> - 若 `.env` 中定义了数据库变量，可先导入：
103+
>
104+
> ```bash
105+
> export $(grep -v '^#' .env | xargs)
106+
> ```
107+
>
108+
> - 执行前建议先备份：
109+
>
110+
> ```bash
111+
> docker exec -i nexent-postgres pg_dump -U $POSTGRES_USER $POSTGRES_DB > backup_$(date +%F).sql
112+
> ```
113+
114+
---
115+
116+
## 🌐 步骤四：验证部署
117+
118+
部署完成后：
119+
120+
1. 在浏览器打开 `http://localhost:3000`
121+
2. 参考 [用户指南](https://doc.nexent.tech/zh/user-guide/) 完成智能体配置与验证

0 commit comments

Comments
 (0)