# HyperNode-AI 部署说明

适用于 Ubuntu 22.04。脚本只安装应用本身，监听 `0.0.0.0:33333`。Nginx、Caddy 或其他反代请自行配置，上游地址使用 `127.0.0.1:33333`。

## 1. 一条命令打开菜单

在 Ubuntu 22.04 服务器上执行。已经是 root 时：

```bash
curl -fsSL https://git.bz121.com/dekun/HyperNode-AI/raw/branch/main/deploy/manage.sh | bash
```

当前用户不是 root 时：

```bash
curl -fsSL https://git.bz121.com/dekun/HyperNode-AI/raw/branch/main/deploy/manage.sh | sudo bash
```

脚本会把仓库克隆到 `/opt/hypernode`，然后打开菜单。已经安装过时，也可以直接运行：

```bash
bash /opt/hypernode/deploy/manage.sh
```

仓库需要能被服务器匿名读取。若上面的地址返回 401，到 Gitea 把仓库设为公开，或给部署机配置该仓库的读取权限。

## 2. 菜单

脚本是交互式的，启动后只有四个选项：

| 选项 | 作用 |
|---|---|
| 1 一键部署 | 安装 Python 依赖、创建系统用户、写入 systemd，并启动服务 |
| 2 一键卸载 | 停止服务并删除程序。数据库要再输入一次 `yes` 才会删除 |
| 3 更新 | 从仓库拉取最新代码，重装依赖并重启。`.env` 和数据库保留 |
| 0 退出 | 离开脚本 |

部署和更新结束时会请求 `http://127.0.0.1:33333/health`，失败会打印最近 50 行服务日志。

重复执行「一键部署」不会覆盖已经存在的 `/opt/hypernode/.env`，也不会删除数据库。

## 3. 安装结果

| 项目 | 位置 |
|---|---|
| 程序 | `/opt/hypernode` |
| 配置 | `/opt/hypernode/.env` |
| 虚拟环境 | `/opt/hypernode/.venv` |
| 数据库 | `/var/lib/hypernode/hypernode.db` |
| systemd | `hypernode.service` |
| 监听 | `0.0.0.0:33333`，进程数固定为 1 |

进程数必须是 1。每日清算跑在这个进程里，开多个 worker 会重复触发定时任务。

常用命令：

```bash
systemctl status hypernode
journalctl -u hypernode.service -f
curl http://127.0.0.1:33333/health
```

接口文档：`http://<服务器 IP>:33333/docs`

手动补跑某一天的清算：

```bash
sudo -u hypernode /opt/hypernode/.venv/bin/python -m app.settle --date 2026-10-09
```

不带日期时，结算上一个已经结束的 UTC 账本日。服务正常运行时，北京时间每天 00:05 会自动执行。

## 4. 反代

脚本不修改 Nginx。同一台机器上的反代把流量转到本机 33333 即可，例如：

```nginx
location / {
    proxy_pass http://127.0.0.1:33333;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
```

当前接口没有登录鉴权。反代若只在本机使用，云安全组不要对公网放行 33333。需要从外网直接访问时，再放行该端口，并在反代或安全组上限制来源。

## 5. 更新与卸载

再次执行同一条 `curl` 命令，或运行 `bash /opt/hypernode/deploy/manage.sh`。

选择 `3` 会执行 `git pull` 后重启服务。选择 `2` 会删除程序；是否删除 `/var/lib/hypernode` 会再问一次，直接回车会留下数据库。