chongming-core/deploy/README.md

# deploy 部署目录说明

本目录包含 chongming 应用在宿主机上的部署与运维相关文件。

## 目录内容

| 文件 | 作用 |
|------|------|
| [install_docker.sh](install_docker.sh) | 一键安装 Docker 引擎并配置国内公网镜像加速（Ubuntu 24.04 / amd64） |
| [docker-compose.yml](docker-compose.yml) | Redis / PostgreSQL / MinIO / Mosquitto(MQTT) / Zenoh Router / Caddy 六类服务的编排定义 |
| [.env](.env) | Compose 使用的连接凭据与环境变量（PostgreSQL 密码、MinIO 账号等，勿提交到仓库） |
| [chongming.service](chongming.service) | chongming 应用的 systemd 服务单元文件 |
| [caddy/Caddyfile](caddy/Caddyfile) | Caddy 反向代理配置（本地 IP + 自签证书，统一 HTTP/HTTPS 入口） |
| [data/](data) | Compose 声明挂载的数据持久化目录（redis / postgres / minio / mosquitto / caddy 子目录），由容器产生，勿手动编辑 |

---

## 1. 安装 Docker

首次在新机器上部署时，先安装 Docker：

```bash
sudo ./install_docker.sh
```

脚本会安装 `docker-ce` 及 Compose 插件，并将国内公网加速源写入 `/etc/docker/daemon.json`（多源容灾）。安装完成后即可使用 `docker compose`。

> 说明：脚本使用的 `mirrors.cloud.tencent.com` 为腾讯云公网镜像站；原内网域名
> `mirrors.tencentyun.com` / `mirror.ccs.tencentyun.com` 仅腾讯云 VPC 内访问，本机不可用。

---

## 2. 部署基础服务（Redis / PostgreSQL / MinIO / Mosquitto / Zenoh）

五个服务分别用于 chongming 的缓存、元数据、对象存储、MQTT 消息与 Zenoh 路由汇聚。

### 部署

> 说明：Mosquitto 与 Zenoh Router 为按需启用项。若只想启动基础三服务（redis/postgres/minio），可加 `--no-recreate` 仅针对目标服务：

```bash
cd deploy
# 启动全部服务（首次会自动拉取镜像并创建容器）
sudo docker compose up -d

# 仅启动消息/路由服务（保留已在运行的 redis/pg/minio）
sudo docker compose up -d mosquitto zenoh

# 仅启动基础数据服务
sudo docker compose up -d redis postgres minio
```

### 服务清单（默认端口）

| 服务 | 容器名 | 端口 | 说明 |
|------|--------|------|------|
| Redis 7 | chongming-redis | 6379 | 支持 appendonly 持久化 |
| PostgreSQL 16 | chongming-postgres | 5432 | 元数据存储 |
| MinIO | chongming-minio | 9000(S3) / 9001(Console) | 对象存储，Web 控制台 |
| Mosquitto 2 | chongming-mosquitto | 1883 | MQTT Broker（WebSocket 9001 默认关闭，避免与 MinIO Console 冲突） |
| Zenoh Router | chongming-zenoh | 7447/tcp、7447/udp | Zenoh 路由节点 |
| Caddy | chongming-caddy | 80 / 443 | 统一反向代理入口（chongming Web / MinIO Console / MinIO API） |

### 连接凭据（见 [.env](.env)）

- PostgreSQL：用户 `postgres` / 密码 `postgres` / 库 `chongming`
- MinIO：`minioadmin` / `minioadmin`
- Mosquitto：匿名连接（如需账号，在 [mosquitto.conf](data/mosquitto/config/mosquitto.conf) 配置）

### 数据持久化

数据保存在 `deploy/data/{redis,postgres,minio,mosquitto}`，通过绑定挂载持久化，容器删除后数据不丢失。所有服务均设置 `restart: unless-stopped`（开机自启）。

### 日常管理

```bash
sudo docker compose ps                       # 查看状态与健康度
sudo docker compose logs -f <服务名>          # 查看日志
sudo docker compose restart <服务名>          # 重启单个服务
sudo docker compose down                     # 停止并移除容器（保留数据卷）
sudo docker compose down -v                  # 停止并移除容器 + 数据卷（慎用，会清空数据）
```

### 健康检查

```bash
sudo docker exec chongming-redis redis-cli ping                        # 期望 PONG
sudo docker exec chongming-postgres pg_isready -U postgres -d chongming # 期望 accepting connections
sudo docker exec chongming-mosquitto mosquitto_sub -p 1883 -t '$SYS/broker/version' -W 2 -C 1
                                                                        # 期望打印版本号
```

### 接入 chongming 说明

**Zenoh Router**：项目 [zenoh_config.json5](../config/zenoh_config.json5) 默认以 `peer` 模式连接 `tcp/127.0.0.1:7447`。本 router 容器把 7447 映射到宿主机，同机部署时应用即可直接连到该 router；若跨机部署，需把 `connect.endpoints` 改为 router 机器地址。

**Mosquitto**：网关默认可内嵌 amqtt Broker（`use_embedded_broker = true`）。要改连本目录的
外部 broker，把 `config.toml` 的 `[<env>.mqtt]` 改为：

```toml
[development.mqtt]
enabled = true
host = "127.0.0.1"
port = 1883
use_embedded_broker = false
```

---

## 2.5 Caddy 反向代理（本地 IP + 自签证书）

Caddy 作为统一 HTTP/HTTPS 入口，反代三个 Web 服务：

| 入口域名 | 反向代理到 |
|----------|-----------|
| `gateway.chongming.local` | 宿主机 chongming Web（`host.docker.internal:8000`，systemd 托管） |
| `s3.chongming.local` | MinIO S3 API（容器 `minio:9000`） |
| `minio.chongming.local` | MinIO Web Console（容器 `minio:9001`） |

> 采用**本地 IP + 自签证书**方案：三站均使用 `tls internal`，由 Caddy 内置根证书签发
> 自签证书，**不走公网 ACME**，适合内网/测试环境。

### 部署

```bash
cd deploy
sudo docker compose up -d caddy
```

首次会自动拉取 `caddy:2-alpine` 镜像；Caddyfile 改动后：
`sudo docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile`

### 访问方式（重要）

1. 先把三个本地域名指向机器 IP，追加到**访问端**（含宿主机、内网其它机器）的 `/etc/hosts`：

```
<本机IP>  gateway.chongming.local s3.chongming.local minio.chongming.local
```

2. 浏览器访问（会提示证书不受信任，自签属正常，添加例外即可）：
   - `https://gateway.chongming.local` —— chongming Web
   - `https://minio.chongming.local` —— MinIO Console（账号见 [.env](.env)）
   - S3 SDK 配置 Endpoint 为 `https://s3.chongming.local`

命令行自测（自签需 `-k`）：

```bash
curl -k https://minio.chongming.local/minio/health/live   # 期望结果含账号名（匿名则 403 也正常）
```

> 说明：MinIO 容器仍保留 9000/9001 对宿主端口映射；若只想统一走 Caddy 入口，
> 可删除 compose 中 minio 的 `ports` 段。

---

## 3. systemd 管理 chongming 应用

[chongming.service](chongming.service) 以非特权用户 `linaro` 运行打包后的 chongming 二进制（Nuitka 产物，`/data/chongming`）。

安装：

```bash
sudo cp deploy/chongming.service /etc/systemd/system/chongming.service
sudo systemctl daemon-reload
sudo systemctl enable --now chongming
```

常用运维命令：

```bash
sudo systemctl status chongming      # 状态
sudo systemctl restart chongming     # 重启（优雅排空，最长 30s）
journalctl -u chongming -f           # 系统日志；应用自身日志在 /data/chongming/logs/
```

> 注意：安装目录、用户、worker 数等以 service 文件注释为准；如部署路径不同，
> 需同步修改 `WorkingDirectory` / `ExecStart`。