hipp-https-agent 0.2.0__py3-none-any.whl

hipp_agent/runner.py

@@ -0,0 +1,266 @@
+"""计划、探测、调用 certbot、安装续期钩子。"""
+
+from __future__ import annotations
+
+import http.client
+import os
+import secrets
+import shlex
+import shutil
+import subprocess
+import sys
+import urllib.parse
+from dataclasses import dataclass
+from pathlib import Path
+
+from hipp_agent.config import (
+    AppConfig,
+    CertificateSpec,
+    ConfigError,
+    certificate_agreed,
+    certificate_email,
+    project_root,
+    validate_for_issue,
+)
+from hipp_agent.install import describe_installed, nginx_reload_args, publish_all
+from hipp_agent.render import certbot_issue_args, format_command, write_snippets
+from hipp_agent.report import push_report, server_label
+
+HOOK_NAME = "hipp-https-reload-nginx.sh"
+HOOK_DEST = Path("/etc/letsencrypt/renewal-hooks/deploy") / HOOK_NAME
+
+
+class PreflightError(RuntimeError):
+    """校验地址还不能被证书机构读到。"""
+
+
+@dataclass
+class IssueOutcome:
+    name: str
+    ok: bool
+    detail: str
+
+
+def certbot_bin() -> str | None:
+    override = os.environ.get("CERTBOT_BIN", "").strip()
+    if override:
+        return override
+    return shutil.which("certbot")
+
+
+def build_plan(config: AppConfig, out_dir: Path) -> str:
+    binary = certbot_bin() or "certbot"
+    lines = [
+        f"配置：{config.path}",
+        f"webroot：{config.webroot}",
+        f"证书客户端：{binary}",
+    ]
+    if certbot_bin() is None and not os.environ.get("CERTBOT_BIN"):
+        lines.append("本机 PATH 中没有 certbot。服务器上执行：sudo apt-get install -y certbot")
+    if config.staging:
+        lines.append("staging 为 true：签出的证书浏览器不信任，不要装到对外 443。")
+    if not config.account_email or not config.agree_tos:
+        lines.append("邮箱未填或 agree_tos 不是 true。issue --apply 会拒绝，先改 config.json。")
+    lines.append(f"本机名称：{server_label(config)}")
+    if config.report_url:
+        lines.append(f"上报：{config.report_url}/api/report")
+    else:
+        lines.append("上报：未配置")
+    lines.append("证书内容有变化时执行 " + " ".join(nginx_reload_args(True)) + "，不重启 Nginx。")
+    lines.append("HTTPS 和 443 端口不由程序配置，请在 Nginx 里自行引用证书文件。")
+    lines.append("")
+    for spec in config.certificates:
+        state = "启用" if spec.enabled else "停用（本机不申请）"
+        lines.append(f"[{spec.name}] {state}")
+        lines.append(f"证书文件：{spec.cert_file}")
+        lines.append(f"私钥文件：{spec.key_file}")
+        lines.append(format_command(certbot_issue_args(config, spec, binary)))
+        lines.append("")
+    written = write_snippets(config, out_dir)
+    lines.append("Nginx 片段：")
+    lines.extend(str(path) for path in written)
+    lines.append("")
+    lines.append("未向证书机构申请。服务器步骤见 doc/99-ops/run.md。")
+    return "\n".join(lines) + "\n"
+
+
+def issue(config: AppConfig, apply: bool, only: set[str] | None = None) -> tuple[int, str]:
+    binary = certbot_bin() or "certbot"
+    if not apply:
+        commands = [
+            format_command(certbot_issue_args(config, spec, binary))
+            for spec in config.certificates
+            if spec.enabled and (only is None or spec.name in only)
+        ]
+        text = "未加 --apply，未调用 certbot。\n" + "\n".join(commands) + "\n"
+        return 0, text
+
+    validate_for_issue(config)
+    _require_root()
+    if certbot_bin() is None:
+        return 127, "找不到 certbot。先执行：sudo apt-get install -y certbot\n"
+
+    webroot = Path(config.webroot)
+    webroot.mkdir(parents=True, exist_ok=True)
+    outcomes: list[IssueOutcome] = []
+    issued: list[str] = []
+    for spec in config.certificates:
+        if not spec.enabled:
+            outcomes.append(IssueOutcome(spec.name, True, "已停用，跳过"))
+            continue
+        if only is not None and spec.name not in only:
+            continue
+        if not certificate_agreed(config, spec):
+            outcomes.append(IssueOutcome(spec.name, False, "所选业务配置未同意服务条款"))
+            continue
+        if "@" not in certificate_email(config, spec):
+            outcomes.append(IssueOutcome(spec.name, False, "所选业务配置未填写账户邮箱"))
+            continue
+        try:
+            for domain in spec.domains:
+                preflight(domain, webroot)
+        except PreflightError as exc:
+            outcomes.append(IssueOutcome(spec.name, False, str(exc)))
+            continue
+        command = certbot_issue_args(config, spec, binary)
+        completed = subprocess.run(command, check=False)
+        if completed.returncode == 0:
+            issued.append(spec.name)
+            outcomes.append(IssueOutcome(spec.name, True, "certbot 完成"))
+        else:
+            outcomes.append(IssueOutcome(spec.name, False, f"certbot 退出码 {completed.returncode}"))
+
+    lines = [f"{item.name}：{'成功' if item.ok else '失败'}。{item.detail}" for item in outcomes]
+    if issued and config.staging:
+        lines.append("演练证书未写入 Nginx 路径。")
+    elif issued:
+        code, text = deploy(config, apply=True, only=set(issued))
+        lines.append(text.rstrip())
+        if code != 0:
+            return code, "\n".join(lines) + "\n"
+    failed = [item for item in outcomes if not item.ok]
+    if not failed and issued and not config.staging:
+        lines.append("若 Nginx 还未引用上述证书文件，请自行配置 HTTPS 和端口后再加载。")
+    return (1 if failed else 0), "\n".join(lines) + "\n"
+
+
+def deploy(config: AppConfig, apply: bool, only: set[str] | None = None) -> tuple[int, str]:
+    if not apply:
+        lines = ["未加 --apply，未写证书，也未重新加载 Nginx。"]
+        for spec in config.certificates:
+            if not spec.enabled:
+                continue
+            if only is not None and spec.name not in only:
+                continue
+            lines.append(f"{spec.name} -> {spec.cert_file}")
+        lines.append("内容有变化时：" + " ".join(nginx_reload_args(True)))
+        return 0, "\n".join(lines) + "\n"
+    if config.staging:
+        return 2, "演练证书不写入 Nginx 使用的路径。\n"
+    _require_root()
+    try:
+        results = publish_all(config, only=only)
+    except ConfigError as exc:
+        return 2, str(exc) + "\n"
+    lines = [f"{item.name}：{item.status}。{item.detail}".rstrip("。") for item in results]
+    lines.append(push_report(config, results))
+    failed = [item for item in results if item.status in ("failed", "missing")]
+    return (1 if failed else 0), "\n".join(lines) + "\n"
+
+
+def report(config: AppConfig, apply: bool) -> tuple[int, str]:
+    if not apply:
+        return 0, "未加 --apply，未上报。\n" + server_label(config) + "\n"
+    results = describe_installed(config)
+    text = push_report(config, results)
+    missing = [item.name for item in results if item.status == "missing"]
+    if missing:
+        return 1, text + "\n缺少证书文件：" + "、".join(missing) + "\n"
+    return 0, text + "\n"
+
+
+def renew(config: AppConfig, apply: bool, dry_run: bool) -> tuple[int, str]:
+    binary = certbot_bin() or "certbot"
+    command = [binary, "renew"]
+    if dry_run:
+        command.append("--dry-run")
+    if not apply:
+        return 0, "未加 --apply，未调用 certbot。\n" + format_command(command) + "\n"
+    _require_root()
+    if certbot_bin() is None:
+        return 127, "找不到 certbot。先执行：sudo apt-get install -y certbot\n"
+    completed = subprocess.run(command, check=False)
+    if completed.returncode != 0:
+        return completed.returncode, f"certbot renew 退出码 {completed.returncode}\n"
+    if dry_run:
+        return 0, "certbot renew --dry-run 完成。未写入 Nginx 路径。\n"
+    code, text = deploy(config, apply=True)
+    return code, "certbot renew 完成。\n" + text
+
+
+def install_hook(config: AppConfig, apply: bool) -> tuple[int, str]:
+    script = _hook_script(config.path)
+    if not apply:
+        return 0, "未加 --apply，未写入钩子。\n将安装到 " + str(HOOK_DEST) + "\n" + script
+    if config.path.name == "config.example.json":
+        return 2, "请先把 config.example.json 复制为 config.json，再安装钩子。\n"
+    _require_root()
+    HOOK_DEST.parent.mkdir(parents=True, exist_ok=True)
+    HOOK_DEST.write_text(script, encoding="utf-8")
+    HOOK_DEST.chmod(0o755)
+    return 0, f"已安装 {HOOK_DEST}\n启用定时续期：sudo systemctl enable --now certbot.timer\n"
+
+
+def _hook_script(config_path: Path) -> str:
+    root = shlex.quote(str(project_root()))
+    python = shlex.quote(sys.executable)
+    config = shlex.quote(str(config_path.resolve()))
+    return (
+        "#!/bin/sh\n"
+        "set -eu\n"
+        f"cd {root}\n"
+        f"exec {python} -m hipp_agent --config {config} deploy --apply\n"
+    )
+
+
+def preflight(domain: str, webroot: Path, timeout: float = 10.0) -> None:
+    challenge_dir = webroot / ".well-known" / "acme-challenge"
+    challenge_dir.mkdir(parents=True, exist_ok=True)
+    token = "hipp-https-" + secrets.token_hex(8)
+    body = secrets.token_hex(16)
+    path = challenge_dir / token
+    path.write_text(body, encoding="ascii")
+    try:
+        status, payload, location = _fetch_no_redirect(
+            f"http://{domain}/.well-known/acme-challenge/{token}",
+            timeout,
+        )
+    except OSError as exc:
+        raise PreflightError(f"{domain} 的校验地址无法连接：{exc}") from exc
+    finally:
+        path.unlink(missing_ok=True)
+    if status == 200 and payload == body:
+        return
+    extra = f"，Location: {location}" if location else ""
+    raise PreflightError(
+        f"{domain} 的校验地址返回 {status}{extra}，没有读到探测文件。"
+        "等待 .well-known/acme-challenge。请在状态页打开配置帮助，自行改好 Nginx。"
+    )
+
+
+def _fetch_no_redirect(url: str, timeout: float) -> tuple[int, str, str | None]:
+    parts = urllib.parse.urlsplit(url)
+    connection = http.client.HTTPConnection(parts.hostname, parts.port or 80, timeout=timeout)
+    try:
+        connection.request("GET", parts.path or "/")
+        response = connection.getresponse()
+        raw = response.read(4096)
+        text = raw.decode("utf-8", errors="replace").strip()
+        return response.status, text, response.getheader("Location")
+    finally:
+        connection.close()
+
+
+def _require_root() -> None:
+    if os.geteuid() != 0:
+        raise PermissionError("申请、续期和安装续期钩子需要 root。")

hipp_https_agent-0.2.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: hipp-https-agent
+Version: 0.2.0
+Summary: 在本机申请和续期 HTTPS 证书，并用令牌向服务端上报
+Requires-Python: >=3.10
+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 hipp-https-agent
+```
+
+安装后得到命令 `hipp-agent`。包在 PyPI 上的名字是 `hipp-https-agent`。
+
+先装好 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 分钟内为程序在运行。

hipp_https_agent-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+hipp_agent/__init__.py,sha256=FS-AC5MjbrgosCNu2py7orZB69iY69Ro4lUHnaFnGO4,102
+hipp_agent/__main__.py,sha256=TK4fT3W8XKhSDiHf4x4ls4asVeeFtLVYZwJnwaDa4c4,3863
+hipp_agent/certinfo.py,sha256=wtTqtDBvRuEF6nBkvn0p5xTjEq9v1j3UgSF-GukI4yQ,1419
+hipp_agent/config.py,sha256=Rof8FQEsn1e0rc6UdLfsJFqORgbR_9JDIEJSt7QSEko,10699
+hipp_agent/daemon.py,sha256=YK_WlxVOqky2szLwirzMiLJWyhmm8kTQHqxijHwuvu8,7751
+hipp_agent/install.py,sha256=MJcrQ7V216SudzxuzLYAH-dK1jDoFrQqFXTQSYodxZ4,8320
+hipp_agent/register.py,sha256=FoP4CVrdcBppN_1LbOjpw3yekK1PjYNGt9LkTxcW4zk,5230
+hipp_agent/render.py,sha256=H-rRziW_1w4G2x_578nkgMId9IlPqqJn-dDsxsWWXvY,3635
+hipp_agent/report.py,sha256=JOkgqiLL_8bqZRVuacRjbKi5gTbygfLc-O1RkNk5wCM,2307
+hipp_agent/runner.py,sha256=qLcKWr8eak0yQUaZUeRE-qh-lYiyeHbVV7jsvfcjzy0,10596
+hipp_https_agent-0.2.0.dist-info/METADATA,sha256=8LeM6Xt1CZTmO6ilstI6-xvYictc0MTArKwBU197ALQ,2796
+hipp_https_agent-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hipp_https_agent-0.2.0.dist-info/entry_points.txt,sha256=nJj7QyFLH_FT9ciFyjjITiqrLZSsN4ylB7IILOLr3VE,56
+hipp_https_agent-0.2.0.dist-info/top_level.txt,sha256=kkb29UBJy4dUEchZcjrdk3Eunk6yYtMMmPNtIBvudq4,11
+hipp_https_agent-0.2.0.dist-info/RECORD,,

hipp_https_agent-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hipp_https_agent-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hipp-agent = hipp_agent.__main__:main

hipp_https_agent-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hipp_agent