# Gateway 升级说明

适用范围：`@rcodex-lab/gateway`

本次联合更新Gateway `1.5.31`与Android/iOS App `1.5.31+238`，包含图片滚轮、缓存、大图切换和缩边修复，以及Console会话列表、Provider分栏和错误配色。现有配置、会话与附件保留。

## 升级前确认

- 现有数据目录已经保留
- 账号、密码、token 和可访问目录配置已确认
- Node.js 版本为 22 或更高
- 当前用户已有可用的 ChatGPT 登录、API Key 或 Provider 凭据

## 标准升级步骤

普通用户默认使用 npm 部署：

```bash
npm install -g @rcodex-lab/gateway
rcodex-gateway setup
rcodex-gateway service install
rcodex-gateway service start
rcodex-gateway service status
```

如果已经安装过 Gateway，升级时执行：

```bash
rcodex-gateway service update
```

该命令在当前 Gateway 所在的 npm 目录更新包，成功后使用新版 CLI 刷新服务定义、重启并显示最终状态。npm 更新失败时不会停止现有服务，也不会自动使用 sudo。

常用服务命令：

```bash
rcodex-gateway service install
rcodex-gateway service start
rcodex-gateway service status
rcodex-gateway service restart
rcodex-gateway service update
rcodex-gateway service stop
rcodex-gateway service uninstall
```

首次安装时需要执行 `service install`。升级后建议再次执行，以便覆盖为当前版本的任务或服务定义；该操作不会覆盖 `gateway.env` 和数据目录。Windows 使用当前用户计划任务，macOS 使用 LaunchAgent，Linux 使用 user-level systemd。这样 Gateway 能继续读取当前用户的 Codex CLI 登录态。

Windows 新安装默认使用 `%LOCALAPPDATA%\rCodex\Gateway\gateway.env`；已有 `C:\ProgramData\rCodex\Gateway\gateway.env` 会继续复用。Windows 计划任务在当前用户登录后无窗口运行，不要求管理员权限或 Windows 账户密码，关闭执行安装命令的终端不会停止 Gateway。升级后必须重新执行 `service install`，以覆盖旧任务定义并移除旧 PowerShell 启动文件；该操作不会覆盖配置和数据。`service start` 会验证后台 PID 和 `/healthz`，`service status` 会显示运行模式、任务、进程、HTTP 健康状态及日志路径。

Gateway npm 包会同时安装官方 `@openai/codex` 运行时，不再要求单独全局安装 Codex CLI。`CODEX_COMMAND` 已废弃：旧 `gateway.env`、系统 PATH、企业统一安装路径，以及 VS Code `openai.chatgpt-*` 扩展内的 Codex 都不会覆盖内置版本，也不需要用户手工删除旧配置。内置运行时不会自动完成账号或 Provider 认证。

需要临时调试时，也可以继续使用 `rcodex-gateway start` 在当前终端前台运行；关闭终端后前台进程会停止。如果没有安装后台服务，升级后停止旧的前台进程，再重新执行 `rcodex-gateway start`。

## 更新状态说明

源码部署与 npm 部署都会检查是否存在新版；当前版本相同或更高时无需更新。仅发现新版且无法在线安装时，才提示在部署设备上更新；检查失败应重新检查，不能据此判断已是最新。

OpenAI 兼容 Provider 的普通对话直接使用 Responses API，无需额外开关或重填凭据。升级 Gateway 后，旧普通对话在下一轮使用已保存的最近历史；编程会话和官方 Codex 登录沿用原链路。停止后可以继续对话，运行中先停止再发送。定时任务仍需确认草稿后启用。

## 定时任务配置

在 Console 自动化任务页或 App 设置的定时任务入口管理任务。任务明确保存 Provider、模型和通知去向，修改从下一次运行生效；旧任务需要补齐配置，暂停状态保留。运行中的临时通知断线由队列重试，不阻止生成结果。

## 从 App 更新 Gateway

App 1.5.30 可从设置中的版本与升级入口检查当前连接空间。

1. 打开“设置 → 版本与升级”，自动检查 App 和当前连接空间的 Gateway。页面显示空间名称与地址；需要更新其他空间时先切换连接。
2. 发现新版后选择“更新 Gateway”，检查目标版本并点击下载并安装。同版本显示“已是最新版本”，检查失败可重新检查；已有安装任务会保留“查看更新状态”入口。
3. 页面显示实际检查、安装、校验与等待重启阶段；没有可靠总量时不显示估算百分比。安装完成后点击“重启并生效”并确认，App 重新连接并核对运行版本后显示成功。

仅全局 npm 安装支持应用内安装；源码部署有新版时展示手动升级说明，需在宿主更新。旧版本缺少接口时先执行 `rcodex-gateway service update`。重启可能中断运行任务，建议任务完成后操作。网络响应丢失时 App 只回查状态，重连最多等待两分钟，之后可手动重新检查。

## 这次版本需要注意什么

- App图片修复使用现有Gateway接口；联合升级可同时获得Console改进。
- Gateway服务升级会短暂断开连接，App和Console可重新连接；不会重放历史定时任务或通知。
- Android和iOS稳定下载入口保持不变，旧安装包与测试包保留。