Metadata-Version: 2.4
Name: hipp-https-agent
Version: 0.2.1
Summary: 在本机申请和续期 HTTPS 证书，并用令牌向服务端上报
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# hipp-https-agent

在需要证书的机器上申请和续期 Let’s Encrypt 证书，并把状态上报到服务端。不需要远程登录这台机器。

服务端地址是 `https://hipp.site/cert/`。程序会自己接上 `/api/...`，不要再加接口路径。末尾斜杠可以留着。

## 安装

在证书机器上用 root 安装。申请证书、写 `/etc/nginx/certs` 和重新加载 Nginx 都需要 root，常驻进程也用这个用户。

```sh
sudo pip install -i https://pypi.org/simple hipp-https-agent
```

安装后得到命令 `hipp-agent`。包在 PyPI 上的名字是 `hipp-https-agent`。需要 Python 3.7 或更高。显式指定官方索引，是为了避免云主机默认国内镜像尚未同步新包时出现 `No matching distribution`。

先装好 certbot，并准备校验目录：

```sh
sudo apt-get install -y certbot
sudo mkdir -p /var/www/acme
```

## 登记

先在 [https://hipp.site/cert/](https://hipp.site/cert/) 用手机号登录，打开「证书端令牌」，按页面上的安装和登记范例操作。证书端名称要填这台机器的 `hostname`。

再用 root 登记，这样配置会写到 root 的家目录，和后面的常驻进程是同一个用户：

```sh
sudo hipp-agent register -s https://hipp.site/cert/ -t <令牌>
```

`-s` 是服务端地址。`-t` 是「证书端令牌」页里的令牌。

配置在 `/root/.config/hipp-agent/config.json`。控制台里与本机 hostname 同名的域名会一并写入。还没有域名时也可以先登记，补上之后常驻进程会自动取回。

## 后台常驻

`hipp-agent run` 是常驻循环：每轮向服务端取配置，按申请、生效、监听推进，并上报心跳。它不会自己退出。直接在终端里跑时，关掉终端进程就没了。

用 systemd 把它留在后台，断线、重启机器之后也会再拉起来：

```sh
sudo tee /etc/systemd/system/hipp-agent.service >/dev/null <<'EOF'
[Unit]
Description=hipp certificate agent
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/hipp-agent --config /root/.config/hipp-agent/config.json run
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now hipp-agent
```

若 `command -v hipp-agent` 不是 `/usr/local/bin/hipp-agent`，先改单元里的 `ExecStart` 再执行。仓库里的 `deploy/hipp-agent.service` 与上面这段相同，给仍从源码安装的人用。

查看是否在跑：

```sh
systemctl status hipp-agent
journalctl -u hipp-agent -n 50 --no-pager
```

停掉或重新拉起：

```sh
sudo systemctl stop hipp-agent
sudo systemctl restart hipp-agent
```

控制台「证书状态」里，最后上报在 3 分钟内为程序在运行。
