# CoderMaMa

**Repository Path**: Lapper/coder-ma-ma

## Basic Information

- **Project Name**: CoderMaMa
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex Mobile Bridge

![Codex Mobile Bridge 宣传海报](docs/assets/codex-mobile-bridge-poster.png)

Codex Mobile Bridge 是一套面向 Codex 桌面端的远程控制系统。电脑端运行 Electron 桌面客户端，内置 Go bridge 连接本机 Codex app-server；手机端通过云端网页查看 Codex 任务进度、历史对话、实时输出，并可以继续发消息、软暂停、中断任务或处理审批。

当前线上入口：

- 官网和云端控制台：[https://a.yueshuzhiyuan.cn](https://a.yueshuzhiyuan.cn)
- 下载页：[https://a.yueshuzhiyuan.cn/download](https://a.yueshuzhiyuan.cn/download)
- 当前桌面端版本：`0.1.3`

## 核心能力

- 手机远程控制 Codex：查看线程、读取历史、发送消息、接入会话、中断任务、处理工具/文件审批。
- 按工作区组织历史：长对话和大量工具输出会折叠显示，移动端通过底部导航快速切换电脑、历史、对话和管理区。
- Electron 桌面端：双击启动、有独立窗口、托盘菜单、任务栏最小化、退出时自动关闭内置 Go bridge。
- 云端账号体系：支持注册、登录、邮箱验证码登录、找回密码、图形验证码、用户协议和隐私政策确认。
- 设备绑定与解绑：用户生成绑定码，桌面端绑定到自己的云端账号；解绑时会同步取消云端关联。
- 管理后台：管理员可以发布 Markdown 公告、查看用户列表、查看设备审计、重置普通用户密码、上传新版本安装包。
- 强制更新：云端可配置 `latestVersion`、`minimumVersion`、下载地址和更新说明；桌面端低于最低版本时必须更新。
- PostgreSQL 持久化：生产环境要求使用 PostgreSQL，不依赖内存存储。

## 架构

```text
手机浏览器
  -> HTTPS/WSS 云端控制台
  -> 云端 WebSocket Relay
  -> 用户电脑上的 Electron 桌面端
  -> 内置 Go bridge
  -> 127.0.0.1 Codex app-server
  -> Codex
```

本地局域网调试也支持直接访问电脑上的 Go bridge：

```text
手机浏览器 -> http://电脑局域网 IP:8787 -> Go bridge -> Codex app-server -> Codex
```

代码拆分：

- `cloud-server`：云端 Go 服务，提供账号、设备、WebSocket relay、公告、版本更新、下载文件等能力。
- `cloud-web`：云端 Vue/Vite 前端，包含官网首页、下载页、登录注册、移动端控制台和管理后台。
- `desktop-shell`：Electron 桌面壳，负责窗口、托盘、自动更新、启动/关闭 Go bridge。
- `desktop-web`：桌面端本地 Vue/Vite 控制台。
- `internal/codex`：Codex app-server WebSocket 客户端与进程启动逻辑。
- `internal/control`：线程列表、读取历史、发送消息、审批、中断等控制逻辑。
- `internal/cloudagent`：桌面端与云端绑定、心跳、命令转发和事件上报。
- `internal/mobile`：本地网页、PIN、WebSocket 和 API 路由。
- `web`：`desktop-web` 的构建产物，由 Go `embed` 打进桌面端 bridge。

## 用户使用流程

1. 打开 [https://a.yueshuzhiyuan.cn](https://a.yueshuzhiyuan.cn)，注册或登录账号。
2. 进入下载页，下载 Windows 安装版或便携版。
3. 双击启动 Codex Mobile Bridge 桌面端。
4. 在云端控制台生成绑定码。
5. 在桌面端“云端绑定”区域粘贴绑定码，点击绑定。
6. 绑定成功后，用手机登录云端控制台即可选择电脑、查看历史、发送消息和处理审批。

桌面端绑定信息会保存在：

```text
%USERPROFILE%\.codex-mobile-bridge\config.json
```

Electron 启动配置会保存在：

```text
%APPDATA%\codex-mobile-bridge-shell\launcher.json
```

## 下载地址

建议给普通用户分享下载页，而不是直接发送 exe：

```text
https://a.yueshuzhiyuan.cn/download
```

当前 Windows 产物：

```text
https://a.yueshuzhiyuan.cn/downloads/desktop/Codex-Mobile-Bridge-Setup.exe
https://a.yueshuzhiyuan.cn/downloads/desktop/Codex-Mobile-Bridge-Setup-0.1.3.exe
https://a.yueshuzhiyuan.cn/downloads/desktop/Codex-Mobile-Bridge-0.1.3-portable.exe
https://a.yueshuzhiyuan.cn/downloads/desktop/latest.yml
```

推荐分发策略：

- 普通用户优先使用安装版：`Codex-Mobile-Bridge-Setup.exe`
- 临时测试或无安装权限场景使用便携版：`Codex-Mobile-Bridge-0.1.3-portable.exe`
- 自动更新依赖安装版、`latest.yml` 和对应 `.blockmap` 文件；便携版更适合手动替换。

## 关闭和卸载

关闭方式：

- 点击窗口右上角关闭按钮：Electron 和内置 Go bridge 会一起退出。
- 使用托盘菜单里的“退出程序”。
- 使用桌面端页面顶部的“退出程序”。

安装版卸载：

```text
Windows 设置 -> 应用 -> Codex Mobile Bridge -> 卸载
```

便携版卸载：

1. 先退出程序。
2. 删除 `Codex-Mobile-Bridge-0.1.3-portable.exe`。
3. 如需清理本机绑定信息，删除 `%USERPROFILE%\.codex-mobile-bridge\config.json`。
4. 如需清理 Electron 启动配置，删除 `%APPDATA%\codex-mobile-bridge-shell\launcher.json`。

## 管理员后台

管理员账号由后端固定邮箱判断，当前管理员邮箱：

```text
shibaizhelianmeng@gmail.com
```

普通用户即使修改前端请求，也会被后端管理员接口返回 `403`。

管理员登录后可以使用：

- 公告发布：支持 Markdown，同一时间只展示一条启用中的公告。普通用户登录控制台后会弹窗展示。
- 桌面端更新：按平台配置最新版本、最低允许版本、下载地址、更新说明和强制更新提示。
- 版本上传：上传 `latest.yml`、安装包、`.blockmap`、macOS zip 等发布文件。
- 用户列表：查看账号、最近登录、在线设备数，并可为普通用户生成临时密码。
- 设备审计：查看设备归属、系统、版本、在线状态和最近心跳。

## 强制更新和 OTA

Windows 安装版接入 `electron-updater` 的 generic provider：

```text
https://a.yueshuzhiyuan.cn/downloads/desktop/
```

发布新 Windows 版本时，至少上传：

```text
dist/electron/latest.yml
dist/electron/Codex-Mobile-Bridge-Setup-<version>.exe
dist/electron/Codex-Mobile-Bridge-Setup-<version>.exe.blockmap
```

发布后在管理后台“桌面端更新”里配置：

- `latestVersion`：最新版本，例如 `0.1.3`
- `minimumVersion`：最低允许版本；桌面端低于该版本时会强制更新
- `downloadUrl`：安装包下载地址
- `releaseNotesMarkdown`：Markdown 更新说明
- `forceMessage`：强制更新提示文案，可留空

桌面端启动时会检查一次云端策略，运行中也会周期性检查。强制更新命中后，用户不能选择“稍后继续使用旧版本”。

macOS 未签名测试包目前主要通过云端策略提示用户下载 zip。正式对外分发建议使用 Apple Developer ID 证书签名并 notarize。

## Windows 构建

前提：

- Go 1.22+
- Node.js 18+ 或 20 LTS
- npm

一键构建：

```powershell
cd D:\CodeMAMA\codex-mobile-bridge
.\scripts\build-windows.ps1
```

或：

```bat
cd D:\CodeMAMA\codex-mobile-bridge
scripts\build-windows.bat
```

输出位置：

```text
dist\codex-mobile-bridge.exe
dist\electron\Codex-Mobile-Bridge-Setup-0.1.3.exe
dist\electron\Codex-Mobile-Bridge-0.1.3-portable.exe
dist\electron\latest.yml
```

`dist\codex-mobile-bridge.exe` 是 Electron 内部使用的 Go bridge，不建议直接发给普通用户。

## macOS 构建

macOS 桌面端应在真实 Mac 上构建，不建议在 Windows 交叉打包 `.app`。

Mac 环境要求：

- macOS 13+
- Node.js 18+ 或 20 LTS
- Go 1.22+
- Xcode Command Line Tools：`xcode-select --install`

Apple Silicon：

```bash
chmod +x scripts/build-macos.sh
scripts/build-macos.sh arm64
```

Intel Mac：

```bash
scripts/build-macos.sh x64
```

输出位置：

```text
dist/electron/Codex-Mobile-Bridge-0.1.3-mac-arm64.zip
dist/electron/Codex-Mobile-Bridge-0.1.3-mac-x64.zip
dist/electron/latest-mac.yml
```

未签名 macOS 包首次打开可能出现安全提示。测试用户可以右键 App 选择“打开”；如果系统提示 App 已损坏，可执行：

```bash
xattr -dr com.apple.quarantine "/Applications/Codex Mobile Bridge.app"
```

## 开发调试

桌面端本地前端：

```powershell
cd desktop-web
npm install --registry=https://registry.npmmirror.com --no-audit
npm run dev
```

云端前端：

```powershell
cd cloud-web
npm install --registry=https://registry.npmmirror.com --no-audit
npm run dev
```

桌面端 Go bridge：

```powershell
go run . -listen 0.0.0.0:8787
```

云端 Go 服务：

```powershell
cd cloud-server
go run . -listen 0.0.0.0:9080
```

常用桌面端参数：

```text
-listen 0.0.0.0:8787
-pin 123456
-codex-url ws://127.0.0.1:18457
-codex-cmd C:\Users\admin\AppData\Roaming\npm\codex.cmd
-start-codex=false
-cloud-url https://a.yueshuzhiyuan.cn
-bind-code ABCD1234
-device-name 我的电脑
```

默认会尝试启动：

```text
codex app-server --listen ws://127.0.0.1:18457
```

Codex app-server 只监听本机，手机和云端只连接 Codex Mobile Bridge，不直接暴露 Codex app-server。

## 云端部署

生产环境使用 PostgreSQL。云端服务启动时要求配置 `DATABASE_URL`。

关键环境变量：

```text
DATABASE_URL=postgres://user:password@127.0.0.1:5432/codex_cloud?sslmode=disable
CODEX_CLOUD_LISTEN=0.0.0.0:9080
CODEX_CLOUD_JWT_SECRET=<long-random-secret>
CODEX_CLOUD_ADMIN_EMAIL=shibaizhelianmeng@gmail.com
CODEX_CLOUD_DOWNLOAD_DIR=/opt/codex-cloud/downloads
CODEX_SMTP_HOST=smtp.163.com
CODEX_SMTP_PORT=465
CODEX_SMTP_USER=<smtp-user>
CODEX_SMTP_PASS=<smtp-auth-password>
CODEX_SMTP_FROM=<smtp-from-address>
```

轻量部署建议：

- PostgreSQL 作为持久化数据库。
- systemd 负责服务启动、开机自启和日志。
- Monit 负责轻量守护、健康检查和异常重启。
- Nginx 负责 HTTPS、静态域名入口和反向代理到 `127.0.0.1:9080`。

健康检查：

```bash
curl http://127.0.0.1:9080/api/health
systemctl status codex-cloud
monit status codex-cloud
```

部署脚本 `scripts/deploy-cloud.py` 通过环境变量读取 SSH 信息和本地二进制路径，不应把服务器密码、SMTP 授权码、JWT 密钥写入仓库。

## 安全说明

- 不要把 Codex app-server、CDP 调试端口或数据库端口暴露到公网。
- 云端必须使用 HTTPS/WSS，当前生产域名已使用 `https://a.yueshuzhiyuan.cn`。
- JWT 密钥、SMTP 授权码、数据库密码、服务器 SSH 密码只应放在服务器环境变量或安全的运维系统中。
- 面向外部用户分发 Windows 安装包时，建议使用可信代码签名证书。未签名或证书信誉不足时，Windows SmartScreen 可能提示未知发布者。
- 自签名证书不适合作为对外分发的静默信任方案，不建议让安装程序静默写入用户根证书。

## 常见问题

### 登录后看不到管理员后台

确认登录邮箱是否等于后端配置的 `CODEX_CLOUD_ADMIN_EMAIL`。管理员权限由后端判断，不依赖前端本地状态。

### 云端绑定返回 401

通常是登录 token 过期、绑定码过期或绑定码不属于当前账号。重新登录云端，重新生成绑定码，再在桌面端粘贴绑定。

### 手机端看不到最新消息

确认桌面端在线、Codex 已连接、当前选择的是正确电脑和正确工作区。长工具输出默认折叠，可以点“展开”查看完整内容。

### 关闭窗口后下次启动失败

当前 Electron 关闭窗口会退出内置 Go bridge。如果仍有端口占用，检查是否手动运行过 `dist\codex-mobile-bridge.exe` 或旧便携版进程。

### 用户是否可以跳过强制更新

当云端 `minimumVersion` 高于用户桌面端版本时，桌面端会强制更新，不能继续使用旧版本。

## 项目宣传语

> 离开电脑，也能掌控 Codex 任务进度。

Codex Mobile Bridge 适合需要长时间运行 Codex、经常离开电脑、又希望随时接管任务进度和审批请求的开发者。