82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
# chongming-cli
|
||
|
||
chongming 网关的命令脚本集合，独立包维护。
|
||
|
||
## 命令
|
||
|
||
| 命令 | 说明 |
|
||
| ------------ | ------------------------------------------- |
|
||
| `build` | 应用构建打包（PyInstaller / Nuitka） |
|
||
| `build_plugin` | 进程插件项目根直接压缩为可部署 zip |
|
||
| `gen_models` | 从插件配置 `*.toml` 生成 Pydantic 模型 |
|
||
| `gen_plugin` | 生成风格统一的 Worker 插件骨架（`--process` 生成进程插件完整项目） |
|
||
| `migrate_plugin` | 内置插件一键迁移为进程插件（`src/plugins/<name>` → `workers/<name>/`） |
|
||
|
||
另有 `chongming_cli.code_content` 模块：将目录下代码文件汇总为 Markdown（`python -m chongming_cli.code_content <dir>`）。
|
||
|
||
## 用法
|
||
|
||
在 chongming 网关项目根目录下（已通过 path/git 依赖安装本包）：
|
||
|
||
```bash
|
||
uv run build pyinstaller # 构建打包（默认：明文模块、不带授权）
|
||
uv run build --only mbank # 仅重新打包 .mbank 模块文件（跳过其余流程）
|
||
uv run build --only mbank,vue # 只执行指定步骤
|
||
uv run build --encrypt --license # 对外分发：加密模块 + 注入厂商授权公钥
|
||
uv run build_plugin demo # 进程插件打包 → dist/demo.zip（= workers/demo/ 直接压缩）
|
||
uv run gen_plugin myplugin # 生成 inline 插件骨架
|
||
uv run gen_plugin myplugin --process # 生成进程插件完整项目（workers/myplugin/）
|
||
uv run gen_models config/workers/myplugin src/plugins/myplugin # inline 插件模型
|
||
uv run gen_models workers/myplugin/config/workers/myplugin workers/myplugin/workers/myplugin # 进程插件模型
|
||
uv run migrate_plugin myplugin --dry-run # 内置插件迁移为进程插件（仅演练）
|
||
uv run migrate_plugin myplugin # 实际迁移：建项目 + 迁移代码/配置/依赖 + 删源
|
||
```
|
||
|
||
`migrate_plugin` 前置检查（命中则拒绝迁移，`--force` 跳过）：插件挂载了自定义
|
||
FastAPI 路由（`APIRouter`，external 插件挂不了，需先改成 TOML `@rpc_method` 端点
|
||
或保持 inline）；插件导入了网关包（`app` / `chongming`，进程插件与网关零导入关系）。
|
||
迁移后依赖从 `plugins_deps.toml` 的 `[<name>]` 节（按代码实际 import 过滤）转入
|
||
新项目 `pyproject.toml`，该节自动注释掉 —— 依赖随插件走，不再进网关 exe。
|
||
|
||
`build --only <step>` 可选步骤：`mbank` / `prepare` / `obfuscate` / `pack` / `clean` / `license_guard` / `vue`，可逗号分隔或重复传多个。
|
||
|
||
`build` 的两个开关默认**都关**（不加参数即内部调试产物：明文模块、不带授权，横幅与构建报告里会回显状态）：
|
||
|
||
- `--encrypt`：打开加密与混淆 —— `.mbank` 加密存字节码并写 `.key` 密钥文件、做 PyArmor 混淆
|
||
- `--license`：打开授权 —— 注入厂商授权公钥（缺公钥则构建失败）、跑授权私钥泄漏守卫
|
||
|
||
打包收集清单分两处：网关本体依赖在根 `config.toml` `[pyinstaller_build_import]`；
|
||
内置插件专属依赖（网关本体不 import、只在插件里用）在根目录 `plugins_deps.toml`
|
||
（按插件分节，可选文件），`pack` 时自动并入 `--hidden-import` / `--include-module`。
|
||
|
||
### Nuitka 打包的环境要求（Linux）
|
||
|
||
- **patchelf 必需**（standalone/onefile 都要）：已列进网关 dev 依赖（`uv sync` 自动带），
|
||
也可 `sudo apt install patchelf`。Nuitka 直到链接完成后才检查它——缺失会白跑一整轮
|
||
编译，build 已改为提前失败提示
|
||
- **链接器**：默认 GNU ld 链接大工程峰值数 GB，小内存机器/WSL 上会被 OOM 杀掉
|
||
（`clang: unable to execute command: Killed`）。检测到 `ld.lld` 时自动经 `LDFLAGS`
|
||
换成 lld（内存与耗时都低得多）
|
||
- **内存档位**（按 `MemAvailable` 自动选）：≥ 6 GB 完整优化（`--lto=yes`）；
|
||
< 6 GB 去 LTO（LTO 链接峰值 3 GB+，实测 GNU ld 与 lld 都会被 OOM 杀掉）；
|
||
< 2.5 GB 再 `--low-memory` 降并发。`CHONGMING_NUITKA_LOW_MEM=1` 强制省内存档、
|
||
`CHONGMING_NUITKA_FULL=1` 强制完整优化
|
||
- **PGO 默认关闭**：Nuitka 4.3 的 `--pgo-c` 与 standalone/onefile 不兼容（Nuitka 自身
|
||
WARNING 后 FATAL），且 profiling 运行会启动程序等它退出——常驻服务会卡死；
|
||
能自行退出的程序可设 `CHONGMING_NUITKA_PGO=1` 打开
|
||
- 失败自动逐档重试：完整优化 → 去 LTO/UPX → 去 LTO/UPX + `--low-memory`
|
||
|
||
## 项目根目录定位
|
||
|
||
脚本需要在项目根目录下读写 `config/`、`src/plugins/`、`workers/` 等路径。
|
||
本包安装位置不固定（site-packages），因此根目录按以下顺序解析：
|
||
|
||
1. 环境变量 `CHONGMING_ROOT`（显式指定项目根）
|
||
2. 当前工作目录向上查找第一个含 `pyproject.toml` 的目录（即项目根）
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
uv pip install -e utils/cli # 本地可编辑安装
|
||
```
|