安装与启动

npm install -g @cloudomni/omnigate

中国大陆用户推荐走 CDN：

OMNIGATE_USE_CDN=1 npm install -g @cloudomni/omnigate

npm 包不内嵌 Go 二进制，postinstall 会从 GitHub Releases 下载对应平台产物，安装期需要联网。

基本命令

omnigate                   # 后台启动服务（默认）
omnigate start             # 后台启动服务
omnigate stop              # 停止服务
omnigate status            # 查看服务状态
omnigate help              # 显示帮助信息

浏览器打开 http://127.0.0.1:17777/manage 进入管理台。

首次运行会在 ~/.omnigate/ 下自动创建数据目录、初始化 SQLite、生成默认 config.yaml，无需手工准备。Windows 下服务以真正的后台模式运行，关闭 CMD 窗口不影响服务。

启动选项

omnigate start --foreground                 # 前台运行（Ctrl+C 停止）
omnigate start --host 0.0.0.0 --port 8080   # 自定义监听地址/端口
omnigate start --db ~/work/og.db            # 覆盖 db 路径（支持 ~ 展开）
omnigate start --log stdout                 # 仅输出到 stdout
omnigate start --config ~/my.yaml           # 指定配置文件

四级优先级：CLI flag > 环境变量 > config.yaml > 代码默认值。启动层配置项见 配置。

数据布局

~/.omnigate/
├── omnigate.db           # SQLite（实体、运行层配置、请求日志、可选内容日志）
├── omnigate.db-wal       # SQLite WAL
├── omnigate.db-shm       # SQLite 共享内存
├── omnigate.pid          # 后台进程 PID 文件
├── config.yaml           # 启动层：监听地址 / 账号密码
└── omnigate.log          # 结构化日志

支持平台

系统	架构
Linux	amd64、arm64
macOS	amd64（Intel）、arm64（Apple Silicon）
Windows	amd64、arm64

卸载

omnigate stop
npm uninstall -g @cloudomni/omnigate
rm -rf ~/.omnigate        # 数据一并清理（可选）

安装排障

中国大陆 / 受限网络优先走 R2 CDN：

OMNIGATE_USE_CDN=1 npm install -g @cloudomni/omnigate

CDN 也慢时，组合 GitHub 镜像：

OMNIGATE_GH_PROXY=https://ghproxy.com npm install -g @cloudomni/omnigate

极慢网络可放宽超时（秒，默认 30）：

OMNIGATE_DOWNLOAD_TIMEOUT=120 OMNIGATE_USE_CDN=1 npm install -g @cloudomni/omnigate

macOS Gatekeeper 拦截未签名二进制：

xattr -d com.apple.quarantine "$(npm root -g)/@cloudomni/omnigate/vendor/omnigate"

离线环境可跳过 postinstall，手动把对应平台的 tarball 解压到 vendor/：

OMNIGATE_SKIP_POSTINSTALL=1 npm install -g @cloudomni/omnigate