# gopm **Repository Path**: kingecg/gopm ## Basic Information - **Project Name**: gopm - **Description**: No description available - **Primary Language**: Go - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-15 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # gopm **Go Process Manager** —— 单二进制的进程管理器,用一条命令托管长驻脚本服务(Node.js / Python / Shell / 任意可执行文件),并可把自身安装为系统服务,实现开机自启与崩溃自愈。 ``` gopm start ./app.js --name api gopm list gopm logs api -f ``` ## 解决什么问题 在单机或边缘节点上托管长驻脚本,常见做法各有短板:手写 `nohup` + 启停脚本没有崩溃自愈与日志轮转;手写 systemd unit / launchd plist 要强绑定解释器绝对路径,换平台还得重写一遍;pm2 体验好但自身依赖 Node,且 `pm2 startup` 生成的 unit 不会加载 `nvm.sh`,用 nvm 装 Node 的服务开机自启极易失败(`env: node: No such file or directory`)。 gopm 的取舍: | | gopm | pm2 | 手写 unit | | --- | --- | --- | --- | | 运行时依赖 | 无(单个 Go 二进制) | 需要 Node | 无 | | 运行时版本声明 | 一等公民:`path` / `system` / `nvm` / `fnm` | 靠 shell 环境 | 手写绝对路径 | | 服务环境(无 shell 初始化) | 文件系统层面解析,不依赖交互 shell | 易失败 | 需人工维护 | | 跨平台服务托管 | Linux systemd / macOS launchd / Windows SCM | 依赖 pm2 支持 | 每平台各写一份 | | 结构化输出 | 所有查询命令 `--json` | `jq` 需转换 | 无 | ## 特性 - **单二进制、零运行时依赖**:`CGO_ENABLED=0`,一个文件管任意语言的长驻进程。 - **运行时解析**:`runtime.source` 支持 `path`(绝对路径)、`system`、`nvm`(版本 / 别名 / 语义化范围)、`fnm`;解析由文件系统探测完成,服务环境下同样可用。`gopm runtime which` 与 `start` 走同一套解析器。 - **进程守护**:崩溃按策略重启、重启计数与 `errored` 状态、内存上限触发重启、`cron_restart` 定时重启、就绪判定(`wait_ready`)。 - **日志直写 + 轮转**:子进程直接写 `out.log` / `err.log`,daemon 不在跑也能读;按大小切分并保留历史,`logs -f` 可跨轮转继续跟随。 - **daemon 接管**:daemon 意外退出时应用继续运行,下次启动按 `meta.yaml` 认领它们。 - **跨平台服务托管**:`gopm install --system` 一键注册为 systemd 服务 / launchd 守护 / Windows 服务,`uninstall` 干净卸载。 - **脚本友好**:统一 JSON 信封 + 稳定退出码,CI/面板可直接消费。 ## 安装 需要 Go 1.22+。 ```bash # 从源码安装到 $GOBIN go install gitee.com/kingecg/gopm/cmd/gopm@latest # 或在仓库内构建(注入版本信息) make build # 产出 ./gopm ``` ## 快速开始 ```bash # 启动一个 Node 脚本(daemon 未运行时会被自动拉起) gopm start ./app.js --name api # 指定运行时来源与版本 gopm start ./app.js --name api --runtime-source nvm --runtime-version 20 # 启动 ecosystem 配置里的全部应用 gopm start gopm.yaml # 查看/观察/读日志 gopm list gopm monit # 实时视图(含 CPU/内存) gopm logs api -f # 生命周期 gopm restart api gopm reload api gopm stop api # 不带名字即停止全部 gopm delete api --purge ``` ## 命令一览 | 命令 | 说明 | | --- | --- | | `gopm start ` | 声明并拉起应用;daemon 未运行会自动拉起 | | `gopm list [filter]` | 列出应用与真实运行状态 | | `gopm describe ` | 单个应用的声明与运行现场 | | `gopm monit` | 实时视图(定期刷新 list 并采样 CPU/内存) | | `gopm logs [name...]` | 读日志;`-f` 跟随、`--stream err` 读错误流 | | `gopm events` | 事件流(起停/崩溃/重启/接管),可按 `sinceSeq` 续传 | | `gopm stop \| restart \| reload \| delete \| reset [name...\|all]` | 应用生命周期(`reload` 在 fork 模式下等价 restart) | | `gopm env ` | 查看应用环境变量(敏感键脱敏为 `***`) | | `gopm config validate \| show \| path` | 配置校验/查看,本地执行 | | `gopm runtime list \| which \| doctor` | 运行时枚举、解析、探测环境诊断 | | `gopm daemon start \| stop \| status` | daemon 生命周期(`start --foreground` 供服务托管) | | `gopm ping` | 探测 daemon 是否在运行(不自动拉起) | | `gopm install \| uninstall` | 安装/卸载系统服务 | | `gopm version` | 版本、构建信息与 JSON schema 版本 | 全局参数:`--json`、`--quiet`、`--no-color`、`--data-dir`、`--config`、`--socket`、`--cwd`、`--no-daemon-spawn`。完整用法见 `gopm --help` 或 [docs/design.md](docs/design.md) §12.1。 ## ecosystem 配置 `gopm start gopm.yaml` 可一次声明多个应用,支持 `defaults` 继承、`env` 插值、`env_file` 合并: ```yaml version: 1 defaults: restart_policy: on-failure max_restarts: 8 log: max_size: 10M retain: 5 apps: - name: api script: scripts/api.js args: ["--port", "3000"] env: NODE_ENV: production DATABASE_URL: "postgres://${DB_HOST}:5432/app" runtime: kind: node source: nvm version: "20" log: max_size: 50M - name: worker script: scripts/worker.py runtime: kind: python source: system restart_policy: always ``` 校验:`gopm config validate --strict`(错误定位到 `file:line:col`),查看合并后的生效配置:`gopm config show`。 ## 安装为系统服务 服务托管的 `start` / `stop` 与 `gopm daemon start` / `gopm daemon stop` 语义一致;`--dry-run` 可先预览将要写入的文件与将执行的命令。 ```bash # Linux(systemd):系统级需要 root sudo gopm install --system sudo gopm install --system --account deploy # 以指定账号运行 gopm install --user # 用户级,不需要 root # macOS(launchd):LaunchDaemon / LaunchAgent sudo gopm install --system gopm install --user # Windows(SCM):需要管理员权限,服务以 LocalSystem 运行 gopm install --system # 卸载 sudo gopm uninstall --system ``` 要点: - 服务环境的 `PATH` 只含系统目录。依赖特定版本 Node 的应用请在配置里声明 `runtime.source`(`nvm`/`fnm`)或显式解释器路径。 - `gopm daemon stop` 停掉服务托管的 daemon 后,systemd(`Restart=always`)与 Windows SCM(恢复策略)会在约 5 秒后重新拉起;需要真正停止请用平台命令(`systemctl stop gopm` / `sc stop gopm`)。launchd 的 `KeepAlive` 只在异常退出时重启,优雅退出不会。 - macOS `--user` 注册的是 LaunchAgent,注销即停止;需要开机常驻请用 `--system`。 - Windows 目前仅支持 `--system`(LocalSystem),`--user` / `--account` 会返回用法错误。 ## 脚本化:JSON 与退出码 所有查询类命令支持 `--json`,stdout 为纯 JSON(人类提示走 stderr): ```json { "schemaVersion": "1", "ok": true, "data": {} } ``` 失败时 `ok=false` 且 `error.code` / `error.message` / `error.hint` 必有值(`hint` 给出可执行的下一步)。退出码稳定可用: | 退出码 | 含义 | | --- | --- | | 0 | 成功 | | 1 | 内部错误 | | 2 | 用法错误 | | 3 | 目标不存在 | | 4 | daemon 不可用且自动拉起失败 | | 5 | 权限不足 | | 6 | 配置非法 / 运行时找不到 / 服务后端不可用 | | 7 | 批量操作部分成功 | ## 数据目录与环境变量 数据目录优先级:`--data-dir` > `$GOPM_HOME` > 平台默认。 | 平台 | 默认数据目录 | | --- | --- | | Linux / macOS(用户级) | `~/.gopm` | | Linux / macOS(`--system`) | `/var/lib/gopm` | | Windows(用户级) | `%LOCALAPPDATA%\gopm` | | Windows(`--system`) | `%ProgramData%\gopm` | 目录内包含 `gopm.sock`、`gopm.pid`、`gopm.lock`、`meta.yaml`、`events.jsonl`、`daemon.log` 与每个应用的 `apps//`。 ## 开发 ```bash make build # 构建(注入版本/commit/构建时间) make fakeapp # 构建测试用 fakeapp make check # gofmt 检查 + go vet + 单元测试 make test-race # 竞态检测 make cross # linux/darwin/windows 交叉编译验证 make ci # 与 CI 完全一致的门禁 make smoke # 纵向切片冒烟(start → list → logs → stop) make acceptance # L1 验收 ``` ## 文档 - [需求文档](docs/requirements.md) —— 目标、非目标、功能与验收标准 - [设计文档](docs/design.md) —— 架构、IPC、监督模型、服务后端、目录布局、命令参考 - [实施计划](docs/implementation-plan.md) —— 任务拆分与当前状态 - [平台说明](docs/platform-notes.md) —— 各平台差异与已知取舍 - [验收测试](docs/acceptance-tests.md) —— L1 验收矩阵 ## License [MIT](LICENSE)