frpsctl 0.2.0__tar.gz

frpsctl-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,118 @@
+name: CI
+
+# 平台范围由设计文档 §3.4 决定：只支持 Linux，因此 CI 只有 Linux job。
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+env:
+  # 契约层需要真实 frps：CI 里按需下载并强校验（不缓存二进制，避免供应链漂移）
+  FRPS_VERSION: "0.71.0"
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: 安装依赖
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install --python .venv/bin/python -e ".[dev]"
+
+      - name: 静态分析
+        run: .venv/bin/ruff check src/ tests/
+
+      - name: 拉取真实 frps + frpc（契约层用）
+        run: |
+          # 用我们自己的 install 下载 + sha256 强校验 —— 顺带验证 §8.6 的信任模型。
+          # frpc 与 frps 在同一个 tar 包里，--with-frpc 不产生额外下载；
+          # 插件的唯一真实调用方是 frpc，没有它就只能靠手工拼报文验证协议。
+          .venv/bin/frpsctl install --version "$FRPS_VERSION" --with-frpc
+          BIN="$HOME/.local/share/frpsctl/bin"
+          echo "FRPSCTL_TEST_BINARY=$BIN/frps-${FRPS_VERSION}" >> "$GITHUB_ENV"
+          echo "FRPSCTL_TEST_FRPC=$BIN/frpc-${FRPS_VERSION}" >> "$GITHUB_ENV"
+          "$BIN/frps-${FRPS_VERSION}" -v
+          "$BIN/frpc-${FRPS_VERSION}" -v
+
+      - name: 单元 + 集成 + CLI 层（覆盖率门禁）
+        run: |
+          # 覆盖率门禁：非契约层的基线是 81%，低于 80% 视为回归（新增代码
+          # 不应把已有覆盖挤掉）。契约层需要真二进制，单独跑、不进覆盖率。
+          .venv/bin/pytest tests/ -q -m "not contract" \
+            --cov=frpsctl --cov-report=term --cov-fail-under=80
+
+      - name: 契约层（设计文档事实基线的自动化守卫）
+        run: .venv/bin/pytest tests/test_facts.py -q
+
+      - name: 故障注入层（异常路径的五项不变量）
+        run: .venv/bin/pytest tests/test_faults.py -q
+
+      - name: 插件契约层（真 frpc → 真 frps → 我们的插件）
+        run: .venv/bin/pytest tests/test_plugin.py -q -m contract
+
+      - name: 端到端冒烟（真 frps 全链路）
+        run: |
+          set -euo pipefail
+          export FRPSCTL_ROOT="$RUNNER_TEMP/smoke/instances"
+          export FRPSCTL_DATA_HOME="$RUNNER_TEMP/smoke/data"
+          mkdir -p "$FRPSCTL_DATA_HOME/bin"
+          cp "$FRPSCTL_TEST_BINARY" "$FRPSCTL_DATA_HOME/bin/"
+          ln -sf "frps-${FRPS_VERSION}" "$FRPSCTL_DATA_HOME/bin/frps"
+
+          free_port() { python3 -c "import socket;s=socket.socket();s.bind(('127.0.0.1',0));print(s.getsockname()[1])"; }
+          BP=$(free_port); DP=$(free_port)
+
+          .venv/bin/frpsctl init --no-input --bind-port "$BP" --dashboard-port "$DP" --allow-ports 6000-6100
+          .venv/bin/frpsctl verify
+          .venv/bin/frpsctl start --health-timeout 10
+          .venv/bin/frpsctl status
+          .venv/bin/frpsctl config set maxPortsPerClient 30
+          .venv/bin/frpsctl status --json
+          .venv/bin/frpsctl doctor
+          .venv/bin/frpsctl stop
+          .venv/bin/frpsctl status
+
+  no-binary:
+    name: 无二进制降级路径（Python 3.13）
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: 安装依赖
+        run: |
+          uv venv --python 3.13
+          uv pip install --python .venv/bin/python -e ".[dev]"
+      - name: 契约层必须整体 skip 而不是失败
+        run: .venv/bin/pytest tests/test_facts.py -q -rs
+
+  contract-070:
+    name: 契约层（frp 0.70.0 下界）
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: 安装依赖
+        run: |
+          uv venv --python 3.13
+          uv pip install --python .venv/bin/python -e ".[dev]"
+      - name: 版本门槛下界的契约验证
+        run: |
+          # 支持范围的下界必须与上界一样可信：§3.6 的门槛是 0.70.0，
+          # 契约层就在这里把它变成可执行断言（本机已实测 21/21 通过）。
+          export FRPSCTL_DATA_HOME="$RUNNER_TEMP/data070"
+          .venv/bin/frpsctl install --version 0.70.0
+          FRPSCTL_TEST_BINARY="$RUNNER_TEMP/data070/bin/frps-0.70.0" \
+            .venv/bin/pytest tests/test_facts.py -q

frpsctl-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,102 @@
+name: Release
+
+# 发布流程（打 tag 触发）：
+#   1. 修改 src/frpsctl/__init__.py 的 __version__
+#   2. 更新 CHANGELOG.md
+#   3. git tag v<version> && git push origin v<version>
+#
+# 版本一致性由本流程强校验：tag 与 __version__ 不一致直接失败——防止发布物
+# 与代码里的版本号漂移。
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: 构建 sdist 与 wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: 校验 tag 与 __version__ 一致
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          python3 - <<'EOF'
+          import os, pathlib, re, sys
+
+          text = pathlib.Path("src/frpsctl/__init__.py").read_text(encoding="utf-8")
+          version = re.search(r'__version__ = "([^"]+)"', text).group(1)
+          tag = os.environ["TAG"]
+          if f"v{version}" != tag:
+              sys.exit(f"tag {tag} 与 __version__ {version} 不一致——先改版本号再打 tag")
+          print(f"版本一致：{tag}")
+          EOF
+
+      - name: 构建
+        run: uv build
+
+      - name: 构建产物自检（wheel 必须包含 py.typed 与全部模块）
+        run: |
+          python3 - <<'EOF'
+          import pathlib, zipfile
+
+          wheel = next(pathlib.Path("dist").glob("*.whl"))
+          names = set(zipfile.ZipFile(wheel).namelist())
+          required = {"frpsctl/py.typed", "frpsctl/cli/__init__.py", "frpsctl/core/lifecycle.py"}
+          missing = required - names
+          if missing:
+              raise SystemExit(f"wheel 缺少文件：{sorted(missing)}")
+          print(f"{wheel.name} 自检通过（{len(names)} 个条目）")
+          EOF
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    name: 创建 GitHub Release
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  pypi:
+    name: 发布到 PyPI（Trusted Publishing）
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/') && vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      # 前置配置（一次性，在 PyPI 网页端）：
+      #   Publishing → Add a new pending publisher
+      #   - Owner: <your-github-user>  Repository: frpsctl
+      #   - Workflow: release.yml      Environment: pypi
+      # 然后在仓库 Settings → Variables 添加 PYPI_PUBLISH=true 启用本 job。
+      # 未配置时本 job 整体跳过，不会把 release 流程染红。
+      - uses: pypa/gh-action-pypi-publish@release/v1

frpsctl-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# 虚拟环境
+.venv/
+venv/
+
+# 测试与类型检查缓存
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# 编辑器
+.idea/
+.vscode/
+*.swp
+
+# 插件运行期产物：审计日志与策略属于本地数据，不进版本库
+plugin-audit.jsonl
+plugin-audit.jsonl.*
+plugin-policy.json

frpsctl-0.2.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# 更新日志
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.2.0] - 2026-09-16
+
+第三轮全量迭代：安全缺口、部署守护、稳定性与发布链路。
+
+### 新增
+
+- `start` / `restart` 在健康 gate（L1 ∧ L2）未通过时以**退出码 12** 收场并向
+  stderr 告警——此前完全静默（退出码 0，脚本会当成成功）。未过 gate 的进程
+  仍被托管：`status` 可见、`stop` 可停。
+- `install --mirror URL`（可重复）与 `FRPSCTL_MIRROR` 环境变量：下载镜像可配置，
+  兑现"下载地址可被镜像替换"的承诺。
+- `service install --user/--group`：systemd 服务账户可指定（默认 `frps`）。
+- `status` 输出 `listen` 行（人读）与 `listen` 字段（JSON），对齐设计文档 §7.4。
+- `status --watch --json` 改为单行 NDJSON，可被逐行消费（`jq -c` 等）。
+- shell 补全（`--install-completion` / `--show-completion`）。
+- PyPI 发布链路：版本号单一来源（hatchling 读 `__init__.py`）、release workflow、
+  CHANGELOG、`py.typed`。
+
+### 修复
+
+- **安全**：`config diff` / `edit` / `set` / `rollback` 的内联表与**跨行结构**
+  （三引号多行字符串、多行内联表/数组）机密不再明文泄露；解析失败但形似含机密
+  时保守打码；裸键名 `token`/`password`/`clientSecret` 同样命中。
+- `config rollback` 每次只产生 **1** 份快照：此前 `rollback_to` 与 `apply_change`
+  各存一份完全相同的内容，10 份历史实际只够 5 次操作，且快照创建在实例锁外。
+- 全局选项前移支持 `--` 终止符：`config set k -- --json` 的字面值不再被搬走。
+- `service install` 前置体检：服务账户不存在、二进制对服务用户不可达、
+  日志目录不可写、**路径位于家目录（`ProtectHome=true`）**——这些过去都要等
+  `systemctl start` 才炸，且错误现场与安装动作相隔很远。
+- unit 的 `ReadWritePaths` 增加**实例目录**：`ProtectSystem=strict` 下其余路径
+  只读，而 frp 默认要往实例目录写 `./frps.log`。
+- `config set` 重建配置时**保留原属主**：systemd 部署把配置移交给服务用户后，
+  再次改配置不会再"夺回"属主导致 frps 读不到。
+- `plugin serve` 的 SIGTERM handler 安装纳入 `try`：安装瞬间收到信号不再绕过
+  审计刷盘（此前 `finally` 尚未生效，进程直接死亡）。
+- 配额检查按用户锁重构：dashboard 查询不再持全局锁，一个用户的慢查询不会串行
+  挂住所有用户的登录链路（frp 侧对插件 HTTP 客户端没有超时）。
+- `install --with-frpc --only-download` 不再切换 frpc 软链，与 frps 语义统一。
+- `log` 改为纯 Python tail：不依赖外部 `tail` 命令，支持日志轮转后自动重开新文件。
+- `plugin init` 生成策略文件改用原子写（此前 `write_text` 存在半截文件与权限窗口）。
+- 健康等待期间进程死亡时按启动失败收尾并清理 `state.json`（不再留下假 RUNNING）。
+- 负数数值选项（`--interval` / `--timeout` / `-n` 等）归入用法错误(2)：
+  此前 `--timeout -1` 会跳过等待直接 SIGKILL——参数笔误造成不可逆动作。
+- `status --watch` 重定向到文件时不再写入 ANSI 清屏码。
+
+### 工程
+
+- CI 增加 `ruff check` 与 80% 覆盖率门禁；`[dev]` 补齐 `pytest-cov` / `ruff`。
+- 新增 70 条回归用例（单元 / CLI / 集成 / 插件各层，总计 296 条）。
+
+## [0.1.0] - 2026-09-15
+
+首个版本。
+
+- 生命周期：`install` / `init` / `start` / `stop` / `restart` / `status` / `log`，
+  含实例锁、三重进程身份校验、启动早退检测、三层健康判定。
+- 配置闭环：`config get|set|edit|diff|rollback`，tomlkit 无损补丁、官方
+  `frps verify` 权威校验、原子写、快照历史、失败自动回滚。
+- 运维面：`doctor` 体检与安全 lint、`service install` systemd 集成、`kick`。
+- 服务端插件：多用户鉴权、端口白名单、代理名/类型约束、`max_proxies` 配额、
+  异步 JSONL 审计；fail-closed 与绑回环硬约束。
+- 五层测试：单元 / 集成 / CLI / 契约（真二进制）/ 故障注入。

frpsctl-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 frpsctl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frpsctl-0.2.0/NOTICE

@@ -0,0 +1,28 @@
+# NOTICE
+
+## 本仓库的许可
+
+frpsctl 自身的代码以 **MIT** 许可发布，全文见 [`LICENSE`](LICENSE)。
+
+## 关于 frp 的许可（重要）
+
+本仓库**不包含** frp 的源代码，也不包含其二进制。
+
+`frpsctl install` 会按需从 [fatedier/frp](https://github.com/fatedier/frp) 的
+官方发布页下载 `frps` 二进制。该二进制是独立的第三方软件，遵循其自身的
+**Apache License 2.0**，与本仓库的 MIT 许可互不相干：
+
+- 它**不随本包分发**，由使用者自行获取；
+- 使用它需要遵守 Apache-2.0 的条款（包括其许可与声明的保留要求）；
+- 本仓库的 MIT 许可**只覆盖 frpsctl 的 Python 代码**，不覆盖那个二进制。
+
+本工具的设计前提正是"把 frps 当作外部可替换依赖"（见设计文档 ADR-4）：
+不 fork、不 patch、不内嵌，始终使用官方原版二进制，并对其做 sha256 强校验。
+
+## 为什么不把这段写在 LICENSE 里
+
+GitHub 的许可识别要求 `LICENSE` 文件**以标准模板开头且基本不被改动**。
+把第三方软件的许可说明附在 MIT 正文之后，会导致该文件无法被识别为 MIT
+（仓库页面会显示 "Other"），从而少一个 license 徽章。
+
+因此拆成两个文件，各归其位：`LICENSE` 只放 MIT 正文，第三方许可说明放这里。