• 简体中文

      • Octop 服务器命令：init、run、service 与 update

      这些命令控制 Octop 服务器生命周期——引导全新安装、启动服务器进程、注册为系统服务并保持最新。首次设置 Octop 时请按顺序运行；后续部署管理或升级时也会用到它们。

      octop init

      引导 ~/.octop/，创建 SQLite 数据库、JWT 密钥和首个管理员账户。首次启动服务器前运行一次即可。

      交互式设置
      非交互式设置
      交互式设置
      octop init

      选项

      选项环境变量描述
      --admin-username TEXTOCTOP_ADMIN_USERNAME首个管理员账户的用户名
      --admin-password TEXTOCTOP_ADMIN_PASSWORD首个管理员账户的密码
      --admin-display-name TEXTOCTOP_ADMIN_DISPLAY_NAME首个管理员账户的显示名称
      --force—引导前清空已有 ~/.octop/ 内容
      --yes—跳过所有交互式提示
      说明

      octop init 对数据库是幂等的——在已有安装上再次运行是安全的，只会应用缺失的迁移。使用 --force 可清空 ~/.octop/ 并完全重新开始。

      octop run

      使用 uvicorn 在前台启动 Octop 服务器。单进程同时提供 Web 控制台、HTTP/SSE API 和 IM 渠道监听。

      默认
      自定义主机与端口
      使用自签名证书的 HTTPS
      使用自有证书的 HTTPS
      默认
      octop run

      选项

      选项默认值描述
      --host TEXT127.0.0.1绑定主机。优先级：本参数 > OCTOP_BIND_HOST > config.json > 默认值
      --port INTEGER8088监听端口。优先级：本参数 > OCTOP_PORT > config.json > 默认值
      --reload / --no-reload关闭启用 uvicorn 自动重载（仅开发环境）
      --ssl / --no-ssl关闭启用 HTTPS
      --certfile PATH—PEM 格式 TLS 证书
      --keyfile PATH—PEM 格式 TLS 私钥
      --log-levelinfo可选：debug、info、warning、error
      注意

      生产环境请勿使用 --reload。自动重载会在文件变更时重启进程，仅用于本地开发。

      说明

      传入 --host 或 --port 会在 uvicorn 启动前把该值写入 config.json。损坏的 config.json 是硬错误——Octop 不会合并进空对象，以免清掉文件其余内容。

      octop service

      将 Octop 注册为系统服务，以便开机自启并在后台运行。

      启动（若未安装则先安装）
      停止
      重启
      检查状态与健康
      启动（若未安装则先安装）
      octop service start
      说明

      octop service 会自动检测平台：Linux 使用 systemd，macOS 使用 launchd。status 子命令会探测 HTTP 健康端点，失败时打印日志提示。可通过 --scope user 或 --scope system（或 OCTOP_SERVICE_SCOPE）强制作用域。在 Linux 上，start 和 restart 会安装 systemd drop-in（octop.service.d/10-nofile.conf），设置 LimitNOFILE=65535。主 unit 文件不会被改写，除非文件缺失或传入 --force-install。要撤销：删除该 drop-in，然后执行 systemctl daemon-reload && systemctl restart octop。

      octop update

      检查 PyPI 上是否有更新的 Octop 版本并自动安装。默认只查稳定版。页面管理 → 应用设置 → 应用更新同样如此，除非你打开预发布。

      检查并安装
      仅检查，不安装
      包含预发布
      检查并安装
      octop update

      选项

      选项描述
      --check / --no-check仅报告可用版本，不安装
      --yes / -y跳过确认提示
      --verbose / -v打印安装器输出
      --allow-prerelease检查和安装时包含 alpha / beta / rc / dev 版本

      octop captcha

      对照本地数据库清除已保存的登录验证码设置。当云验证码配置错误（密钥不对、厂商不可达、主机名未加白名单）导致所有人无法进入页面时使用——设置页本身也需要登录。

      octop captcha reset

      登录会回退到内置滑块。这条命令不会改环境文件里的 OCTOP_CAPTCHA_*；如果锁定是它们造成的，请自行取消。若 octop run 已在运行，请重启。

      octop user

      octop user 子命令全部离线操作本地 SQLite：create、list、set-email、passwd、role、disable、delete。CLI 没有 login 子命令，也不往 cli_state.json 写 JWT。固定默认用户用 octop config set-user。

      改密示例：

      octop user passwd <用户名> --password <密码>

      完整示例见 渠道与定时任务：octop user。

      octop clean

      重置 CLI 状态或清空整个 ~/.octop/ 目录。具有破坏性——运行前请仔细阅读帮助。

      仅清除 CLI 状态（保留数据）
      清空整个 ~/.octop/ 目录
      跳过确认提示
      仅清除 CLI 状态（保留数据）
      octop clean

      选项

      选项描述
      （默认）删除 ~/.octop/cli_state.json（固定的 default_user / default_agent）
      --all清空整个 ~/.octop/
      --yes跳过确认提示
      --dry-run只打印将删除的路径
      注意

      octop clean --all 会删除数据库、工作区和所有配置。操作前请确保已运行 octop backup create。

      octop config

      查看或编辑 ~/.octop/cli_state.json（固定的默认用户、专家）。

      查看当前 CLI 状态
      固定默认 --user
      查看当前 CLI 状态
      octop config show

      子命令

      子命令描述
      show打印当前 CLI 状态
      set-user固定默认 --user

      octop completion

      生成并安装 Shell 命令补全。

      输出 bash 补全脚本
      输出 zsh 补全脚本
      安装到 ~/.zshrc 或 ~/.bashrc
      输出 bash 补全脚本
      octop completion show --shell bash
      提示

      运行 octop completion install 后，重新打开终端或执行 source ~/.zshrc（或 source ~/.bashrc）即可启用补全。

      octop version

      打印已安装的 octop 版本。与全局选项 -v, --version 等效。

      octop version