# Offline 打包与部署说明

这套离线方案只放在 `offline/` 目录，不改项目原有部署脚本。

## 仓库内文件

- `offline/export-offline-bundle.sh`
- `offline/deploy-prod-offline.sh`
- `offline/deploy-full-offline.sh`
- `offline/init-full-db-offline.sh`
- `bot-images/build.sh`
- `bot-images/README.md`

## 1. 如何打包

完整模式：

```bash
./offline/export-offline-bundle.sh --mode full
```

生产模式：

```bash
./offline/export-offline-bundle.sh --mode prod
```

可选参数：

```bash
./offline/export-offline-bundle.sh --mode full --env-file .env.full --output-dir offline-dist
```

说明：

- `full` 会导出 `backend`、`nginx`、`postgres`、`redis` 镜像。
- `prod` 只导出 `backend`、`nginx` 镜像，数据库和 Redis 由客户自己提供。
- 导出产物默认放在 `offline-dist/`。

## 2. 打包后会生成什么

每次导出会得到一个目录和一个压缩包，例如：

```text
offline-dist/dashboard-nanobot-full-offline-YYYYMMDD_HHMMSS/
offline-dist/dashboard-nanobot-full-offline-YYYYMMDD_HHMMSS.tar.gz
```

产物根目录主要包含：

- `docker-compose.yml`
- `.env`
- `import-images.sh`
- `init-db.sh`
- `start.sh`
- `stop.sh`
- `README.txt`

其中导出的 `docker-compose.yml` 会带中文注释，方便客户直接按注释修改端口、挂载路径、数据库与 Redis 配置。

此外还会带上：

- `offline/` 内部离线脚本
- `sql/` 数据库初始化 SQL
- `data/templates/`
- `data/skills/`
- `data/model/`

也就是说，发给客户的是一套部署产物，不需要把源码仓库一起发过去。

## 3. 客户如何部署

客户拿到压缩包后按下面做：

```bash
tar -xzf dashboard-nanobot-full-offline-YYYYMMDD_HHMMSS.tar.gz
cd dashboard-nanobot-full-offline-YYYYMMDD_HHMMSS
./import-images.sh
```

如果你还另外给了客户 `nanobot-base-v0.1.5.tar.gz` 这类 Bot 基础镜像包，也需要先导入：

```bash
gunzip -c nanobot-base-v0.1.5.tar.gz | docker load
```

然后修改：

- `.env`
- 如果要改挂载路径，再改 `docker-compose.yml`

再初始化数据库：

```bash
./init-db.sh
```

最后启动：

```bash
./start.sh
```

停止：

```bash
./stop.sh
```

## 4. 客户主要改哪些配置

`.env` 里通常需要改：

- `PUBLIC_HOST`
- `NGINX_PORT`
- `HOST_BOTS_WORKSPACE_ROOT`
- `DOCKER_NETWORK_SUBNET`
- `PANEL_ACCESS_PASSWORD`

`prod` 模式额外常改：

- `DATABASE_URL`
- `REDIS_ENABLED`
- `REDIS_URL`

`full` 模式额外常改：

- `POSTGRES_SUPERPASSWORD`
- `POSTGRES_APP_PASSWORD`

## 5. 挂载路径怎么改

默认挂载关系在导出产物里的 `docker-compose.yml`：

- `./data:/app/data`
- `${HOST_BOTS_WORKSPACE_ROOT}:${HOST_BOTS_WORKSPACE_ROOT}`
- `/var/run/docker.sock:/var/run/docker.sock`

如果客户现场要换宿主机路径，直接改产物里的：

- `.env` 中的 `HOST_BOTS_WORKSPACE_ROOT`
- `docker-compose.yml` 中的 volume 挂载项

建议：

- `HOST_BOTS_WORKSPACE_ROOT` 必须是宿主机绝对路径
- 保留 `/var/run/docker.sock:/var/run/docker.sock`
- `./data` 最好保留在产物目录下，方便整体交付

## 6. 数据库说明

`prod` 模式：

- 客户需要提前准备 PostgreSQL
- 推荐直接执行：
  - `./init-db.sh`
- 这个脚本会自动使用 `.env` 里的 `DATABASE_URL` 执行 `sql/create-tables.sql` 和 `sql/init-data.sql`
- 如果客户想手工执行，也可以执行：
  - `sql/create-tables.sql`
  - `sql/init-data.sql`

`full` 模式：

- 产物里包含 PostgreSQL 和 Redis 镜像
- `./init-db.sh` 可以手工初始化数据库
- `start.sh` 启动完整栈时也会自动初始化数据库

## 7. Bot 基础镜像说明

- 离线部署包里的 `./import-images.sh` 只负责导入当前离线包自带的业务镜像。
- 如果客户现场还需要运行依赖 `nanobot-base` 的 Bot 容器，则还需要额外导入单独提供的 `nanobot-base-*.tar.gz`。
- 导入命令：

```bash
gunzip -c nanobot-base-v0.1.5.tar.gz | docker load
```

- 如果没有导入这类镜像，Dashboard 主服务可以启动，但相关 Bot 运行时容器可能会因为缺少基础镜像而启动失败。

## 8. 看哪份文档

- 研发/打包同学看本文件：`offline/README.md`
- 客户部署时看导出产物根目录里的：`README.txt`
- 如果要单独构建和导出 `nanobot-base` 镜像，看：`bot-images/README.md`