# Boss 服务器连接与部署说明

## 1. 服务器信息

- 主机：`106.53.170.158`
- 用户：`ubuntu`
- 域名：`boss.hyzq.net`

当前优先连接方式不是手敲 `ssh`，而是仓库外已经建好的 skill：

- `~/.codex/skills/boss-server-debug/SKILL.md`

## 2. 连接方式

```bash
ssh ubuntu@106.53.170.158
```

或直接使用 skill：

```bash
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" health
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status boss-web --no-pager"
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" login
```

密码当前已经存入本机 macOS Keychain，避免后续 Codex 线程因背景压缩丢失连接方式。

## 3. DNS 与 HTTPS 前提

当前要启用 `https://boss.hyzq.net`，必须先满足：

- `boss.hyzq.net` 的 A 记录指向 `106.53.170.158`

仓库里已提供：

- `deployment/Caddyfile`
- `scripts/bootstrap-server.sh`
- `scripts/deploy-server.sh`
- Codex skill：`boss-server-debug`

DNS 生效后，`Caddy` 会自动申请和续签证书。

## 4. 服务器部署步骤

本地发起部署：

```bash
cd /Users/kris/code/boss
./scripts/deploy-server.sh
```

当前 `deploy-server.sh` 已支持：

- 优先读取 macOS Keychain 中保存的服务器密码
- 若 Keychain 不可用，则读取 `BOSS_SERVER_PASS`
- 远端 `npm run build` 前自动清理 `.next`
- 重启 `boss-web` / `caddy` 后自动执行 `curl -fsS http://127.0.0.1:3000/api/health`

如果需要覆盖服务器默认环境，可在服务器写入：

```bash
sudo cp /opt/boss/.env.server.example /opt/boss/.env.server
sudo systemctl restart boss-web
```

当前最重要的开关是：

- 默认固定码：`BOSS_AUTH_VERIFICATION_MODE=fixed`
- 临时切到真实邮件：`BOSS_AUTH_VERIFICATION_MODE=email`

部署服务器邮件栈：

```bash
cd /Users/kris/code/boss
./scripts/install-server-mail.sh
```

当前 `install-server-mail.sh` 会：

- 先复用 `deploy-server.sh` 同步代码和重启 Web
- 再通过 `boss-server-debug` skill 包装器执行远端邮件安装
- 在服务器上安装 `Postfix + Dovecot + swaks`
- 创建本机测试邮箱 `bossmail`
- 配置别名 `verify@boss.hyzq.net` 与 `no-reply@boss.hyzq.net`
- 将 Caddy 已签发的 `boss.hyzq.net` 证书同步给邮件服务
- 安装 `boss-mail-cert-sync.timer`，用于后续证书轮转同步

如果需要在服务器上单独补环境：

```bash
cd /opt/boss
sudo ./scripts/bootstrap-server.sh
npm install
npm run build
sudo systemctl restart boss-web
sudo systemctl restart caddy
```

## 5. 本机 device-agent 启动

```bash
cd /Users/kris/code/boss
./scripts/start-local-agent.sh ./local-agent/config.example.json
```

健康检查：

- 本机 agent：`http://127.0.0.1:4317/health`
- 云端 web：`http://127.0.0.1:3000/api/health`

## 6. 为什么要保留这份文档

这份文档的作用是避免 Codex 在背景信息压缩后遗忘：

- 服务器地址
- 登录用户
- 部署入口脚本
- HTTPS 的实际前提条件
- 本机 device-agent 的启动方式

## 7. 当前部署状态（2026-03-25）

已完成：

- 服务器 `106.53.170.158` 已安装 `nodejs` 和 `caddy`
- 服务器已安装 `Postfix`、`Dovecot`、`swaks`
- `/opt/boss` 已同步当前项目代码
- `boss-web.service` 已启动
- `caddy.service` 已启动
- `postfix.service` 已启动
- `dovecot.service` 已启动
- `http://127.0.0.1:3000/api/health` 已返回成功
- `http://127.0.0.1:3000/api/v1/conversations` 已返回新聚合数据
- `Caddy` 日志中已经出现 `certificate obtained successfully`，说明服务端证书申请链路已跑通
- 邮件服务已经监听 `25 / 465 / 587 / 993`
- 服务器本机已通过 `swaks` 走 `127.0.0.1:587 + STARTTLS + AUTH LOGIN` 成功发送测试邮件到 `verify@boss.hyzq.net`
- 测试邮件已经进入 `/home/bossmail/Maildir`
- `boss-web` 已支持 email 模式，并已通过临时写入 `/opt/boss/.env.server` 做过一次真实邮件验证码投递验证

当前需要继续复核的点：

- 当前本机环境下 `dig +short boss.hyzq.net` 仍返回 `198.18.1.188`
- 当前本机环境下 `curl -I http://boss.hyzq.net` 已返回 `308`
- 当前本机环境下 `curl -I https://boss.hyzq.net` 已返回 `HTTP/2 307 /auth/login`
- 当前本机环境下 `curl https://boss.hyzq.net/api/health` 已返回 `{"ok":true,...}`
- 当前本机环境下 `curl https://boss.hyzq.net/api/v1/conversations` 已返回真实聚合数据
- 当前本机环境下 `nc -vz boss.hyzq.net 25 587 993` 已全部成功
- 服务器本机 `dig +short boss.hyzq.net` 已返回 `106.53.170.158`
- 服务器本机 `curl --resolve boss.hyzq.net:443:127.0.0.1 https://boss.hyzq.net -I` 已返回 `307 /auth/login`
- 服务器本机 `curl https://boss.hyzq.net/api/health` 已返回 `{"ok":true,...}`
- 服务器本机 `curl https://boss.hyzq.net/api/v1/conversations` 已返回真实聚合数据

因此当前结论更新为：公网 `443` 已经实际可用，`Caddy` 配置本身没有问题，而且域名下的 Web API 已经可以直接返回健康探针和业务数据；服务器邮件栈也已经上线，公网 `25 / 587 / 993` 当前可达。后续如果要继续排障，重点应放在“为什么当前网络下 `dig` 显示的是 `198.18.1.188`”这个入口结构，以及邮件域名的 SPF / DKIM / DMARC / MX 收口，而不是继续假设 443 没打开