msageha/tplink-deco-be85-api

# Deco BE85 API 这是一个使用 FastAPI + Pydantic 封装 TP-Link Deco BE85 本地 Web API（即 Deco 应用程序内部调用的 API）的 REST 服务器。您可以通过本地网络进行状态获取以及 Wi-Fi 开关等操作。 ## 工作原理 重现了与 Deco 管理界面相同的登录流程。 1. `POST /cgi-bin/luci/;stok=/login?form=keys` … 获取用于密码加密的 RSA 公钥 2. `POST /cgi-bin/luci/;stok=/login?form=auth` … 获取用于签名的 RSA 公钥 + `seq` 3. 为每个会话生成随机的 AES-128-CBC 密钥/IV 4. 将请求正文进行 AES 加密，并将签名进行 RSA 加密（53 字节的数据块） - 登录时的签名: `k=&i=&h=&s=`（包含 AES 密钥/IV） - 登录后的签名: `h=&s=` - `hash = md5("admin" + password)` … 认证后的 endpoint 会验证此 hash 5. 通过 `form=login` 获取 `stok` 和 `sysauth` Cookie，并在后续请求中使用 加密处理位于 `src/deco/crypto.py`，登录/通信位于 `src/deco/client.py`。 ## 设置 在 `.env` 中填写认证信息（变量名保持不变）。 ``` USERNAME= PASSWORD= # 任意（デフォルト値） DECO_HOST=http://172.16.1.1 ACCOUNT=admin # 署名 hash に使うローカルアカウント名（通常 admin のまま） VERIFY_SSL=false TIMEOUT=30 ``` `PASSWORD` 是本地认证的主体。`USERNAME`（电子邮件）是用于云端的 TP-Link ID， 不会发送到本地 API（仅为兼容性从 `.env` 中读取）。 安装依赖（也可使用 `make setup`）: ``` uv sync --extra test ``` 可以通过 `make setup-env`（复制 `.env.example`）使用模板来准备 `.env`。 ## 结构 采用 `src/` 布局的 virtual 项目（无需构建）。执行和测试时通过 `pythonpath=src` ／`--app-dir src`／`PYTHONPATH=src` 来解析包。 ``` src/ deco/ Deco ローカル API クライアント（FastAPI 非依存・単体利用可） crypto.py / client.py / exceptions.py api/ FastAPI Web 層: routes.py / schemas.py / service.py config.py Settings（pydantic-settings） main.py FastAPI アプリ tests/ オフライン単体テスト（deco.crypto・api.schemas） scripts/ smoke.py(疎通) / probe.py(読み取り探索) / sniff.py(UI 復号解析) ``` `deco/` 负责协议层（加密、登录、通信），`api/` 负责 Web 层，实现了职责分离。 ## 启动 ``` make up-dev # = uv run uvicorn main:app --reload --app-dir src --host 127.0.0.1 --port 8000 ``` - Swagger UI: http://127.0.0.1:8000/docs - 连接路由器采用延迟登录（在首次调用 API 时登录）。遇到 401/403 或 会话过期时，会自动重新登录并重试 1 次。 ### Docker ``` make build-image # docker build -t deco-be85-api:latest . docker run --rm -p 8000:8000 --env-file .env deco-be85-api:latest ``` 多阶段构建（`uv` 构建阶段 → `python:slim` 运行阶段，以非 root 用户执行）。认证信息 在运行时通过 `--env-file .env` 等方式注入（不包含在镜像中）。 ## 接口 | Method | Path | 描述 | | ------ | -------------------------- | -------------------------------------- | | GET | `/api/health` | 服务器状态与登录情况 | | POST | `/api/login` | 显式登录 | | POST | `/api/logout` | 登出 | | GET | `/api/dashboard` | 概况（网络/CPU/内存/Deco 台数/连接数）| | GET | `/api/devices` | Deco 单元（mesh node）列表 | | GET | `/api/clients` | 已连接客户端列表（`?online_only=true`）| | GET | `/api/network/wan` | WAN IPv4 状态 | | GET | `/api/network/internet` | 互联网连接信息（IPv4/IPv6） | | GET | `/api/network/lan` | LAN / DHCP DNS / WAN IP | | GET | `/api/network/ipv6` | IPv6 启用状态 | | GET | `/api/network/performance` | CPU / 内存使用率 | | GET | `/api/network/mac-clone` | MAC 克隆设置 | | GET | `/api/wireless` | 获取 Wi-Fi 设置 | | POST | `/api/wireless` | 按频段开启/关闭 Wi-Fi | | POST | `/api/wireless/config` | 修改 Wi-Fi 设置（SSID/密码/enable 等）| | GET | `/api/wireless/power` | 无线电波（DFS 支持等） | | GET | `/api/device/mode` | 操作模式（region/workmode/sysmode） | | GET | `/api/device/time` | 时间与时区设置 | | GET | `/api/clients/blocked` | 被屏蔽的客户端列表 | | GET | `/api/cloud/device-info` | 云端联动信息（model/role 等） | | GET | `/api/system/component-info` | ERP/省电等组件信息 | | GET | `/api/system/switch-list` | UI 功能开关 | | GET | `/api/system/log-types` | 可导出的日志类型 | | POST | `/api/reboot` | 重启 Deco（必须提供 `confirm=true`） | | POST | `/api/raw` | 指向任意 endpoint 的通用透传 | ### Wi-Fi 切换示例 ``` curl -X POST http://127.0.0.1:8000/api/wireless \ -H 'Content-Type: application/json' \ -d '{"band":"band5_1","network":"host","enable":false}' ``` `band` 为 `band2_4` / `band5_1` / `band6`，`network` 为 `host` / `guest`（通过 enum 进行验证）。 ### 修改 Wi-Fi 详细设置 `/api/wireless/config` 针对 `admin/wireless?form=wlan` 执行 `operation:write`。可以为每个 `band`×`network`(host/guest) 指定 `enable` / `ssid` / `password` / `enable_hide_ssid` / `channel` / `channel_width` / `mode` （仅发送指定的字段）。对于 `ssid`/`password`，**如果以明文传递，系统内部会进行 base64 编码**（因为路由器是以 base64 格式保存的）。 ``` # ゲスト Wi-Fi の SSID とパスワードを変更 curl -X POST http://127.0.0.1:8000/api/wireless/config \ -H 'Content-Type: application/json' \ -d '{"band":"band5_1","network":"guest","settings":{"enable":true,"ssid":"My Guest","password":"secretpass"}}' ``` ### 通用透传 `/api/raw` 可直接调用任意的 Deco endpoint。响应会直接返回已解密的完整信封 （`result`/`error_code` 或 `success`/`data`）。 ``` curl -X POST http://127.0.0.1:8000/api/raw \ -H 'Content-Type: application/json' \ -d '{"path":"admin/client?form=client_list","operation":"read","params":{"device_mac":"default"}}' ``` - `path`: `admin/?form=

` 格式的相对路径（拒绝 `://` 和 `..`） - `operation`: `read`/`write`/`load`/`list`/`get`/`set`/`add`/`edit`/`remove`/`operate`（enum） - `params`: 任意附加参数（可省略） ### 重启示例（破坏性操作） ``` curl -X POST http://127.0.0.1:8000/api/reboot \ -H 'Content-Type: application/json' -d '{"confirm":true}' ``` ## 开发工具 使用 ruff（lint + 格式化工具）、ty（类型检查）、pre-commit。 ``` make format # ruff format . make lint # ty check . + ruff check . make check # ruff format --check + ruff check + ty check（CI 相当） # pre-commit（標準フック + ruff-format + ruff + ty / Dockerfile は hadolint を manual stage） make precommit-install # フックを git に登録 make precommit # 全ファイルに対して実行 ``` ruff 配置位于 `pyproject.toml`（line-length 88 / lint: C,E,F,I,N,NPY,PD,UP,W）。 ty 配置也位于 `pyproject.toml`（`[tool.ty]`、`unresolved-import = "ignore"`，排除 scripts/tests）。 ## 测试 / 验证 ``` make test # uv run pytest make cov # coverage run -m pytest + report make smoke # 実機への疎通スモーク（読み取りのみ・設定変更なし） ``` `.claude/verify.sh` 用于 Stop hook，在离线状态下执行 `ruff format --check` + `ruff check` + `ty check` + `pytest`（不会触碰实际设备）。 ## CI（GitHub Actions） `.github/workflows/` 中有 2 个工作流（在 PR、main push 或手动时启动）: - `ci.yaml` … `lint`任务（`ruff format --check` + `ruff check` + `ty check`）和 `test`任务（`uv sync --locked --all-extras --dev` → `pytest`） - `pre-commit.yaml` … `pre-commit run --all-files`（标准 hook + ruff/ruff-format。 因为 ty 与 CI lint 重复，所以设为 `SKIP=ty`） uv 通过 `astral-sh/setup-uv` 引入，Action 使用 SHA 固定版本。依赖更新通过 `.github/dependabot.yml`（针对 github-actions / uv 每周执行）。 ## 注意事项 - 假定在本地网络内（同一子网）使用。 - 根据 Deco 的固件不同，响应的字段可能会有所差异。 由于主要模型也会保留未知字段（`extra="allow"`），请一并确认 `/docs` 中的原始 JSON。 ## 免责声明 / Disclaimer 本项目为 **TP-Link 非官方项目**，与 TP-Link 公司没有任何关系。 我们通过逆向工程使用 Deco 未公开的本地 API。 - 请**仅对您拥有管理权限的设备**使用。 - 随着固件更新，API 可能会未经通知发生改变。 - 本软件按“原样”（AS IS）提供，不提供任何保证。 对于因使用而产生的任何损害，作者不承担任何责任。 ## 鸣谢 / Acknowledgements 登录的加密流程（RSA + AES-CBC + 签名）是参考以下公开的逆向工程成果重新实现的。 - [AlexandrErohin/TP-Link-Archer-C6U](https://github.com/AlexandrErohin/TP-Link-Archer-C6U) （GPL-3.0）— TP-Link/Deco 的加密登录步骤 - 通过分析 BE85 本体的 Web UI（`tpEncrypt.js` 等），确认了 `md5("admin"+password)` 签名以及 `device_mac` 参数等特定机型的行为 ## 许可证 / License [GPL-3.0-or-later](LICENSE)。这与上述参考实现采用 GPL-3.0 许可证保持一致。

标签：AV绕过, Docker 部署, FastAPI, TP-Link, 智能家居, 物联网, 网络运维, 请求拦截, 路由器, 逆向工具