InstaBox Panel

基于 Cloudflare Workers 的私人多账号管理面板，带真实交互式 Web 终端。

• 文件管理：目录浏览、文本预览、原始文件下载、新建目录、重命名和确认删除；支持指定目录多文件上传、进度、取消和逐个同名覆盖确认。大文件自动分片并在机器上校验合并，支持刷新后续传及临时分片清理，单文件最多 20 GiB。详见文件管理说明。
• 端口转发：按机器查看公开端口与 HTTPS 地址，发布新端口、改名、复制地址和确认取消转发；多个账号可访问时可切换操作账号。
• 多账号添加、别名、启停同步、同账号 Key 替换与移除；身份去重。
• 完整分页读取机器，合并多个账号可见的同一机器。
• 每 10 秒刷新；后台标签页暂停轮询，失败时逐步退避到最长 60 秒。
• 暂停、恢复、启动、停止确认；持久化幂等请求、任务进度和操作记录。
• xterm.js 终端：ANSI 颜色、Unicode、控制键、窗口缩放、复制粘贴、字号、页面内最大化、手动重连。
• 非模态浮动终端：拖动标题栏移动、四角缩放、页面内最大化、最小化和延迟关闭，同时打开多台机器的终端并操作后台页面。
• 远程桌面：noVNC 画面、人工接管／交还 AI、分辨率调整、操作记录、缩放、最大化和重连；与终端共享 8 个窗口额度。
• 快照管理：按机器或账号查看，创建完整／仅系统盘快照，确认名称后删除；保存进度和断网重试请求持久化到 D1。
• 菜单路由：全部机器、各账号、操作记录和 Telegram 设置可直接访问，刷新及浏览器前进/后退会恢复对应页面；页脚提供仓库和使用指南链接。
• 每分钟定时保活：默认关闭，可选全天或每天最多 5 个时间窗口，支持跨午夜与时区；暂停时自动恢复。
• Telegram 私人机器人：查询账号、机器和状态，恢复/暂停机器；离线通知默认关闭，按离线事件去重。
• 绑定 D1 后自动建表；首次设置管理员账号密码，之后通过内置登录保护管理接口与终端。
• 密码加盐哈希；API Key 使用 AES-256-GCM 加密保存，登录 Cookie 为 HttpOnly。
• 桌面和手机界面，本地演示，后端及浏览器测试。

需要 Node.js 22.12+。

npm ci
npm run dev

打开 http://127.0.0.1:5173 。

这是显式的演示模式，不连接真实账号和机器。首次访问会展示管理员设置页，请使用至少 12 个字符的示例密码。演示登录信息与机器数据只在当前页面内存中保存，刷新页面重置；生产环境保存到 D1。演示账号表单可使用 ibk_demo_example；ibk_demo_error 用于查看账号失效状态。演示终端只模拟 help、ls、pwd、clear 和部分控制键，不执行本机或远端命令。

生产构建不包含演示接口。真实连接需要部署到 Cloudflare 的 HTTPS 地址，可直接使用 workers.dev。项目没有预置真实 API Key、管理员密码、Cloudflare 凭据或公网部署地址。

Windows PowerShell 如果阻止执行 npm.ps1，请改用 npm.cmd / npx.cmd。

推荐流程：部署 Worker → 在 Cloudflare 后台绑定 D1 为 DB → 打开网站设置管理员 → 添加 InstaBox 账号。

正常部署无需填写源码中的数据库 ID，无需手动执行 SQL，也无需预先配置管理员密码或加密密钥。

包括保活和 Telegram 在内，都只需绑定 DB，不需要配置 AUTOMATION_SECRET 或手动生成加密密钥。后台密钥由程序自动生成并保存在 D1；保活和离线通知还需要定时任务正常触发。

通过 Cloudflare 后台部署：

1. 将本项目的完整源码提交并推送到自己的 Git 仓库，例如 GitHub。仓库应包含 package.json、package-lock.json、wrangler.jsonc、index.html、TypeScript/Vite 配置，以及 src/、migrations/、tools/、tests/ 等源码目录；不能只上传 README。node_modules/、dist/ 和本地数据库无需上传。

2. 在 Cloudflare 控制台进入 Workers & Pages，创建 Worker 并连接该仓库，使用 Workers Builds 部署。

3. 选择包含 package.json 和 wrangler.jsonc 的项目根目录，填写以下构建配置：

   配置	值
   Worker 名称	instabox-panel，与 wrangler.jsonc 中的 name 一致
   根目录	package.json 所在目录；源码在仓库顶层时使用默认仓库根目录
   构建命令	npm run build
   部署命令	npx wrangler deploy

4. 完成首次部署。默认开启 workers.dev，可以使用 Cloudflare 分配的 HTTPS 地址访问，也可以之后绑定自己的域名。

也可以在本地项目目录执行以下命令完成部署，再按下一节到 CF 后台绑定数据库：

npm ci
npx wrangler login
npm run deploy

如果构建提示 ENOENT: Could not read package.json，请检查该次构建使用的仓库、分支和提交是否包含源码：

• GitHub 上只有 README：将本地源码提交并推送，再构建包含源码的最新提交；只在本地保存文件并不会上传到 GitHub。
• package.json 位于仓库子目录，例如 InstaBoxPanel/package.json：将 CF 构建根目录设置为 InstaBoxPanel，构建命令和部署命令保持不变。
• package.json 已在仓库顶层：使用默认仓库根目录，并确认 CF 构建的是包含该文件的分支和提交。

1. 准备一个 D1 数据库：可以在 Cloudflare 的 D1 页面新建，也可以选择已有数据库与其他应用共用。
2. 进入 Workers & Pages → 刚部署的 Worker → Bindings（绑定）→ Add binding（添加绑定）。
3. 绑定类型选择 D1 database，变量名必须填写 DB（大写），然后选择目标数据库。数据库自身的名称可以任意命名。
4. 保存绑定，并按控制台提示完成部署或应用更改。
5. 打开 Worker 的 HTTPS 地址。如果此前显示数据库未绑定，点击页面上的“重试连接”。

DB 是 D1 资源绑定，不是普通文本环境变量。正常部署不需要修改 wrangler.d1.jsonc；该文件只供可选的手动迁移命令使用。

主配置使用 Workers 上传元数据 keep_bindings: ["d1", "secret_text", "secret_key"] 保留控制台设置的 D1 绑定，并保留 Wrangler 默认保护的密钥绑定，后续部署不会按本地空配置删除它们；该字段通过 Wrangler 的 unsafe.metadata 传递。这是 Wrangler 的实验性配置，升级 Wrangler 后应重新运行 npm run worker:check 检查输出。

首次打开自动初始化 insb_ 表，并进入“设置管理员账号”页面。填写账号与至少 12 个字符的密码，确认后直接进入面板。第一次成功设置后永久关闭设置入口；以后使用同一账号密码登录。没有默认账号密码，也无需配置 Cloudflare Access 或额外的加密环境变量。

首次设置允许第一位成功提交者建立管理员；部署后先完成自己的设置，再分享访问地址。请将密码保存到密码管理器。

在面板添加 InstaBox 账号。每个账号在官方 Profile → API keys 创建专用 Key，授予 machines:write，它已包含读取权限。不需要 machines:delete。

添加账号会用 /v1/me 和完整机器列表验证身份与读取权限。写权限不足会在机器控制或终端建连时失败，不通过试暂停来测试权限。官方的机器写权限同时包含命令执行和终端。

如果希望另加 Cloudflare Access，可在 Zero Trust 配置域名保护，它作为内置登录之外的额外入口保护。程序不再要求 Access 的团队域名、AUD 或允许邮箱。

登录页面请求 /api/session，提交设置和登录时也会检查表。查询明确报出 no such table: insb_… 时，程序执行随 Worker 打包的初始化 SQL，然后继续处理请求。不是所有数据库错误都代表未初始化：绑定缺失、数据库损坏、SQL 不兼容等会正常返回错误。

建表与索引使用 IF NOT EXISTS，并放在 D1 事务批次中执行；同时访问不会创建多个管理员或覆盖已有数据。部分非管理员表缺失时可以重建，但不会恢复丢失的数据或重置密码。

所有显式索引也带 insb_ 前缀。初始化脚本只操作这些表与索引，不使用其他应用的 accounts、actions 或 d1_migrations。共用 D1 时，表名前缀提供命名隔离；共享同一数据库的应用仍有整个数据库的读写权限。

无需手动执行迁移。可选的 npm run db:local / npm run db:remote 用于维护，使用独立 wrangler.d1.jsonc；执行前将其 database_name 和 database_id 改为目标库，迁移记录仍写入 insb_d1_migrations。

密码使用随机盐和原生 PBKDF2-HMAC-SHA-256（100,000 次，512 位派生结果）；其中一半用于密码验证，另一半用于保护随机生成的数据加密密钥。Workers 原生 PBKDF2 的迭代上限为 100,000。API Key 使用 AES-256-GCM 和账号 ID 绑定保存。

登录会话使用 256 位随机 Cookie，有效期 12 小时，设置 Secure、HttpOnly、SameSite=Strict。D1 只保存会话哈希，数据密钥由会话 Cookie 再次加密；客户端 JavaScript 不读取密钥或 Cookie。写请求验证 Origin 和 X-Panel-Request，终端建连也验证登录与 Origin。登录限流按 IP 和全局 15 分钟窗口记录到 D1。

登录页面与静态资源可公开加载，机器管理接口和 WebSocket 终端必须登录。退出删除当前服务端会话并关闭当前页面的终端。当前版本没有邮件找回密码，请备份 D1 并妥善保存密码，不要通过删除管理员记录重置旧账号。未开启自动化时，密码仍是解锁原凭据的必要信息；开启后，拥有完整数据库权限的人也可以恢复后台数据密钥。

本项目面向私人自用，信任拥有 D1 权限的人具有完整控制权。自动化密钥与加密数据都在同一数据库中，AES-GCM 不提供“数据库泄露后仍无法解密”的安全边界；数据库、备份以及共用该库的其他应用应受到同等保护。网页端仍保留管理员登录、CSRF、Webhook 身份验证，也不会通过接口返回密钥或 Token。

从旧版 Access 登录升级时，如果库中已有加密账号，请在首次设置前临时保留原 KEY_ENCRYPTION_SECRET。程序会先验证它能解密旧凭据，再用新管理员密码保护该密钥；设置成功后可以移除这个环境变量。新安装不需要它。

针对 1–5 台机器，默认采用 每 1 分钟检查一次。Cloudflare Cron 支持分钟级触发，并非最低只能 5 分钟。程序只创建一个 Cron，统一处理保活和已开启的离线通知。

截至 2026-10-22，Workers 免费额度是每天 100,000 次请求；D1 是每天 5,000,000 行读取、100,000 行写入。基础写入按每轮 2 次调度锁写入、每台 1 次检查结果写入估算；表中的 2/5 分钟仅用于比较。程序默认的 1 分钟方案，基础写入约占 D1 免费写入额度的 10.08%，为目标的 20%–25% 留出余量。

这不是整个 Cloudflare 账号用量的保证：恢复任务、索引更新、Telegram 消息、页面轮询、其他应用及异常重试都会增加用量。Workers 向 InstaBox 发出的子请求不按额外 Worker 入站请求计费，但仍有每次执行的子请求限制。Free 计划还限制每次 Cron 的 CPU 时间为 10 ms；等待网络不等于 CPU 时间。请上线后观察 Workers 和 D1 的实际统计，而不是仅按 Cron 次数估计。单轮后台请求最多 35 次，其中通知最多使用 25 次、前 60 秒，预留至少 10 次请求给最多 5 台机器保活。账号较多时轮换通知检测顺序，预算耗尽的检测在后续分钟继续。

1. 在 CF 后台将 D1 数据库绑定为 DB，部署新版本。无需额外的 Secret 或手动执行迁移。
2. 在 Settings → Trigger Events / Cron Triggers 确认存在 * * * * *。部署配置已包含此触发器，无需再添加第二个。Cron 配置传播可能需要几分钟。免费账号所有 Worker 合计最多 5 条 Cron；报错 10072 表示条数已满，改变频率不能解决，需要释放一条不再使用的 Cron 或接入共享调度。
3. 登录面板，在机器行的终端按钮旁点击心跳图标，选择保活模式并保存。

首次开启保活或绑定机器人时，程序自动生成 32 字节随机后台密钥并保存到 D1。Cron 使用数据库中的密钥读取当前账号凭据，不依赖浏览器 Cookie、管理员密码或 AUTOMATION_SECRET；关闭网页和退出登录后继续运行。API Key 和机器人 Token 仍加密存放，后台密钥也在同一库中，数据库拥有者能够解密它们。

旧版升级：已有数据库会自动补建后台密钥表。原 AUTOMATION_SECRET 还在时，登录面板或下一次 Cron 会自动迁移旧保活密钥及机器人 Token，原保活配置和 Webhook 保留；迁移完成后可删除这个旧 Secret。若已提前删除旧 Secret，登录并打开面板也会用登录会话恢复保活密钥；机器人若提示凭据无法读取，重新填写原 Bot Token 并保存即可，不必重新配置 Secret。不要删除 insb_automation_keys 中的密钥，备份时应包含该表。

• 不保活：默认值，不自动恢复机器。
• 全天保活：每轮查询状态，仅当机器为 suspended 且无未完成操作时调用 resume。
• 指定时间范围：每天重复，最多 5 段，默认时区 Asia/Shanghai；支持 22:00–06:00 这样的跨午夜范围。开始时间包含在内，结束时间不包含；不允许重叠，窗口外不主动暂停机器。
• running 不重复发恢复请求；stopped 需手动启动；正在启动、暂停或恢复等过渡状态等待完成。对运行中机器盲目调用 resume 不能当作可靠保活协议。
• 这项功能是在自动暂停后恢复，并不阻止机器先进入暂停。通常在下一次分钟检查后发起恢复，另需唤醒耗时；Cron 调度、网络和上游服务均可能产生延迟，不保证连续零中断在线。
• 开启保活时，手动暂停也可能被下次检查恢复。需要长时间暂停，请先关闭保活。停用或移除账号后，不再对其机器执行保活。
• 自动恢复也写入操作记录。重复 Cron 不并行提交同一任务；响应丢失时复用原幂等键。明确失败后的再次恢复至少间隔 5 分钟，避免反复失败耗尽额度。
• CF 的免费额度与 InstaBox 的机器运行费用是两回事；保活会增加实际运行时间，受 InstaBox 的额度与权限约束。

依据：Workers 计费 · D1 计费 · Workers 限制。

1. 绑定 DB，并确认 Worker 已通过 HTTPS 部署；不需要配置额外的后台 Secret。
2. 在 Telegram 的官方 @BotFather 创建专用机器人，取得 Bot Token。先向自己的机器人发送 /start，允许它向你发送私信。
3. 获取你自己的 Telegram 数字用户 ID，不要填写 @用户名 或群组 ID。私人聊天 ID 与该用户 ID 相同。
4. 登录面板，点击右上角 Telegram，填写 Token 和私人聊天 ID。离线通知默认不勾选。
5. 点击“绑定机器人”。面板会验证机器人与私人聊天，自动注册 /api/telegram/webhook；保存后不再显示 Token。

只接受绑定用户在私人聊天中发送的命令，其他用户和群组消息会被忽略。Webhook 同时验证 Telegram 的随机 Secret 请求头，不能通过直接调用该 URL 控制机器。请勿将机器人 Token 放到公开仓库。

如果另外启用了 Cloudflare Access，需仅对 /api/telegram/webhook 配置允许 Telegram 回调的入口规则，否则 Telegram 无法通过 Access 登录。该路径仍由应用内的 Webhook Secret 与聊天身份校验保护。

推荐发送 /start 或 /accounts，使用消息下方的按钮依次选择账号、机器和操作。列表支持上一页、下一页和刷新；状态页提供按当前状态可用的恢复/暂停按钮，暂停需再次点击“确认暂停”。按钮导航优先更新原消息，消息无法编辑时发送新消息。离线通知附有“查看状态”按钮。机器名和账号名会安全转义，消息使用粗体标题、状态图标及可复制的机器 ID。

旧版升级：在面板的 Telegram 设置中保存一次（Token 可留空），以订阅按钮回调；再发送 /accounts 获取新列表。按钮有效期 7 天，重新保存绑定后旧按钮失效，可随时重新获取列表。新增表自动初始化，无需手动迁移。按钮同样校验 Webhook Secret、私人聊天和绑定用户；短标识避免长 ID 超过 Telegram 的 64 字节限制，同一操作按钮重复点击复用原请求。

手动命令也可继续使用：账号可使用不含空格的唯一别名或面板中的完整账号 ID，机器使用完整 ID。恢复/暂停显示“已受理”时，任务仍在执行，可点击“查看状态”或使用 /status 查询；结果也保存在面板操作记录。重复 Webhook 不会重新执行同一个已处理命令。

通知与保活共用每分钟的 Cron，不需要另加定时器。开启后检查所有已启用账号的机器，首次检查建立基线；后续从运行变为暂停、停止、异常或从完整列表消失时通知。网络错误或 API 查询失败不会被直接判定为机器离线。

同一段持续离线只提醒一次，恢复运行后再次离线才会再次提醒。发送失败保留待发消息并重试，即使机器随后被保活恢复，也会补发离线事件并注明当前已恢复。共享机器不会因为单个账号看不到它就被判定删除；仅在所有已启用账号的完整列表均检查成功、且均未发现它时通知。周期性检测无法捕获两次检查之间发生并恢复的短暂离线。若 Telegram 已收到但回复在网络中丢失，极端情况下仍可能重复送达。关闭通知不影响查询和机器控制；解除绑定会停止 Telegram 控制和通知，保活设置保留。

尚未提供真实机器人 Token 时，本地测试使用模拟 Telegram API，不能替代部署后实际收发验证。

不需要额外 VPS、SSH 私钥或长期 SSH token：

浏览器 xterm.js
  → 同源 WebSocket /api/accounts/:id/machines/:machineId/terminal
  → Worker 验证管理员登录与 Origin，解密账号 API Key
  → InstaBox /v1/machines/:id/terminal?session=panel&wake=0
  → 真实 PTY 登录 Shell

它使用官方 WebSocket 终端协议，提供 SSH 终端的交互体验；不是通用 TCP SSH 客户端或 SFTP 工具。

• 二进制帧传输终端字节，文本帧传输 resize/session/exit/taken/error 控制信息。
• 使用独立的 panel 持久会话。一个会话只有一个查看者；被其他页面接管后不会自动抢回。
• 最小化后，窗口收起至右下角，连接与输出继续保留；点击入口或机器行的终端按钮会恢复原位置、大小及字号。最小化没有自动断开倒计时。
• 点击窗口的 × 会收起并开始 60 秒倒计时；期间重新打开取消倒计时，到期移除窗口并断开连接。右下角入口旁的 × 立即断开并移除窗口。计时在当前前端页面执行；浏览器休眠或节流后，恢复页面时会检查实际截止时间。
• 页面刷新、关闭页面或退出登录会断开当前页面的连接；路由切换不会。断开连接不等于结束远端持久 Shell，使用重连按钮可恢复会话及近期输出；未发送的输入不会自动重放。
• wake=0 避免连接隐式唤醒机器。暂停或停止时，先按按钮恢复或启动。
• 终端输入和输出属于活动，可能延长机器运行时间；机器列表的 GET 查询不会。
• ANSI 颜色、Vim、top、tmux 等由真实 PTY 支持。输入过程的语法高亮取决于远端 Shell，例如 Fish 或 zsh-syntax-highlighting；面板不会自行修改机器配置。
• Ctrl+C / Ctrl+D / Ctrl+L / Ctrl+R、Tab、方向键和 Esc 传给终端。Esc 不关闭终端窗口。
• 终端是非模态浮动窗口，不遮罩或禁用后面的页面。拖动标题栏移动，四个角均可调整大小，对角位置保持不变，并受最小尺寸及视口边界限制；点击窗口置顶。可以同时保留最多 8 台不同机器的终端（包括已收起窗口），重复打开同一机器会恢复并聚焦已有窗口。
• 标题栏包含复制、粘贴、字号、最大化/还原和关闭按钮；连接状态放在左下方，已连接为亮绿色，断开为橙红色，并提供重连按钮。
• 最大化铺满当前网页，双击标题栏也可切换。原先的全屏错误来自对原生 dialog 请求浏览器全屏；现在使用页面内最大化，不需要浏览器全屏权限。使用浏览器自身的 F11 可进一步隐藏浏览器界面。
• Ctrl+Shift+C / Ctrl+Shift+V 用于复制粘贴，也有标题栏按钮。Ctrl+W、Ctrl+L 等可能被浏览器或系统保留，可点击底部快捷键按钮。
• 复制粘贴需要 HTTPS 和浏览器许可。远端 OSC 52 剪贴板命令被禁用。
• 登录会话在 WebSocket 建连时鉴权。退出会关闭当前页面的终端并阻止该会话再次连接；其他页面已经建立的终端不会由服务器立即撤销。结束它们请关闭对应窗口；必要时暂停机器或在 InstaBox 撤销 API Key。
• 官方当前每个用户最多允许 8 个打开的终端。平台更新、网络和机器生命周期操作都可能断开连接。

运行、暂停和停止是不同状态。暂停通常保留内存和进程；恢复也可能回退到冷启动，操作记录会根据 runtime.processesPreserved=false 提示。runtime.ready 单独表示服务是否就绪。

每个操作先写 D1，再向上游发送 Idempotency-Key。202 只代表受理，完成任务查询后才显示成功。同一请求重试复用原 key；提交后断网显示“结果待确认”，可以在操作记录中“重试原请求”。6 天后停止使用原请求重试，避免超过上游 7 天的幂等保存期后重复执行。

Web、Telegram 和保活自动恢复使用同一份操作记录，并显示“操作备注：来自 Web / 来自 TG / 来自保活定时器”。来源由服务端确定并持久化；重试原请求不会覆盖原始来源。定时检查机器运行正常、窗口外跳过或 TG 仅查询状态时不会新增机器操作记录，避免每分钟刷屏。升级前没有来源信息的历史记录显示“历史记录，来源未记录”，不猜测来源；新增来源表会自动创建，无需手动 SQL。

关闭页面后，上游任务继续运行。重新打开可从 D1 找回未完成任务。账号有未确认任务时暂不能移除，避免丢失查询凭据。移除账号清空凭据并保留审计记录，不调用机器删除接口。

账号状态相互独立，一个 Key 失效不影响其他账号。超过 30 秒的数据标记过期，查询出错保留最后一次成功结果。每个账号最多读取 30 页；异常游标或超限会明确报错，不会悄悄返回部分机器。

npm run check
npm test
npm run build
npm run worker:check
npm run test:browser

• 后端测试使用本地真实 D1 和 workerd、模拟上游，不读取真实凭据。
• 端口测试覆盖列表、发布、改名保留地址、确认取消、账号和权限隔离、固定及保留端口校验、204、响应丢失、异常数据及恶意链接；浏览器另验证复制、账号切换、限额、读取失败、暂停机器和手机布局。
• 覆盖自动建表、并发首次设置、密码登录、过期与退出会话、限流、旧凭据保留、加密、CSRF、分页、账号隔离、密钥替换、操作幂等和断网恢复；共库测试预置其他应用的同名表与索引，确认初始化及操作不会修改其数据。
• WebSocket 测试在两个本地 Workers 间代理真实连接，验证 UTF-8/控制字节、resize、Origin 防护和凭据不外泄。
• 自动化测试覆盖仅绑定 DB 的保活和机器人、后台密钥自动生成与旧版迁移、保活时间窗口、真实 workerd 定时事件、Cron 去重、并发启用上限、状态判定、失败冷却、响应丢失重试、跨面板/机器人/定时任务的并发操作、通知预算隔离、Telegram 身份限制、Webhook 保存失败、命令幂等、共享机器离线事件去重及恢复后通知补发。
• 浏览器测试覆盖首次设置、密码登录、保活模式与 5 个时间范围、Telegram 设置、暂停恢复、账号管理、路由刷新与前进/后退、页脚链接、多终端四角缩放与最大化、最小化/恢复及移动端退出。另以模拟 WebSocket 和浏览器时钟验证保留连接、60 秒断开、取消倒计时、立即断开和退出清理。截图及报告保存在 test-results/。Telegram 测试覆盖富文本转义、按钮分页、长 ID、身份校验、过期/重新绑定、暂停确认、重复回调和离线通知按钮。
• 浏览器测试优先使用 Windows 上已安装的 Edge/Chrome。其他环境可设置 PLAYWRIGHT_EXECUTABLE_PATH，或先执行 npx playwright install chromium。
• 桌面与快照验证覆盖接管／交还、最小化、移动端、快照新增／名称确认删除、明确失败后的修改重提与断网后的原请求重试。桌面协议使用本地真实 WebSocket 服务和 noVNC，核对 RFB 画面像素、键鼠输入、只读及状态失联后的输入禁用；Workers 代理另有真实 WebSocket 转发测试。

没有真实账号 Key 或机器人 Token 时，本地测试只能验证实现和协议转发，不代表已通过真实 Cloudflare 和 Telegram 的端到端验证。部署后建议按以下顺序验收：

1. 使用一台可中断的测试机器验证手动暂停、恢复与终端，确认实际组织权限和终端可用性。
2. 在 CF 后台确认 DB 和唯一的 * * * * * Cron，无需添加 Secret。开启测试机全天保活，暂停机器并关闭网页；等后续 Cron 后重新登录，核对机器、保活最近检查及操作记录。Cron 配置更新可能需要等待传播。
3. 验证时间窗口内恢复、窗口外不恢复，结束后关闭测试保活。
4. 绑定私人机器人，验证 /accounts、/machines、/status、/resume 和 /suspend；其他用户发命令应无响应。开启通知后先等待一轮建立基线，再暂停测试机，确认收到一次通知而非每分钟重复发送；关闭通知和解除绑定后应停止通知。
5. 观察 Workers 的 Cron 执行结果及 CPU 时间、D1 每天读写量。免费 Cron 每次仅有 10 ms CPU，必须用真实统计确认；不要仅凭本地测试和每日调用次数判断额度安全。

提供可独立使用的 一键安装脚本，用于 Debian/Ubuntu 上的原生安装、systemd 管理和自动端口转发；在 InstaBox 中自动发布一个 HTTPS 入口。重复执行会保留密码及其他编辑器设置。

将脚本放到目标 Linux 主机后执行 bash install-code-server.sh，详见 部署、存储占用及使用说明。

点击机器行的端口转发图标，或进入机器详情点击端口，查看现有转发。支持发布端口、修改名称、复制／打开公网地址和确认取消转发。改名保留原地址；更换端口时先发布新端口，再取消旧转发。

查看需要 machines:read，修改需要 machines:write。每台最多公开 16 个端口，端口范围 1024–65535；5901、6768 及平台配置的控制端口保留。服务应已在机器中运行；发布端口本身不会启动服务。

这是为机器上的 HTTP 服务提供公网 HTTPS 地址，不提供通用 TCP/UDP 转发。任何持有地址的人都能访问，请为敏感服务设置登录保护。机器暂停或停止时地址暂不可用；取消转发会使地址失效并断开现有连接，机器内的服务继续运行。

无需新增 D1 绑定或数据库迁移。详细操作、接口和错误处理见 端口转发说明。

机器行的显示器图标和详情页的“桌面”可打开远程桌面。首次连接为只读，点击“人工接管”后可在“交还 AI”左侧选择 1024×768、1280×720、1600×900 或 1920×1080；“适应窗口”保留服务端当前分辨率并缩放画面。实际修改需要 VNC 服务端支持动态桌面尺寸。接管后也可操作鼠标键盘及双向复制纯文本：发送本机剪贴板到虚拟机，或在虚拟机复制后点击“复制到本机”；收到虚拟机剪贴板的提示显示在控制状态右边。复制到本机由用户点击确认，需 HTTPS 和浏览器剪贴板许可；旧版 VNC 剪贴板格式可能不支持 Unicode。“交还 AI”、最小化或关闭窗口会交还控制并清除暂存文本。状态失联时禁用输入；桌面断线后使用“重新连接桌面”。机器未运行时需先恢复／启动，未安装桌面时可在窗口中安装。终端与桌面合计最多保留 8 个窗口。

点击机器行的快照图标查看该机器快照，或使用“快照库”的账号入口查看全部快照。新增时可填写名称、说明并选择是否包含 /data；运行中或完全停止且没有进行中操作的机器可创建，暂停中的机器需先恢复。创建后显示“保存中”，可用后才算完成。删除必须输入完整快照名称。

快照 Key 另需 images:read、images:write、images:delete 权限。完整快照包含 /data 中的文件和凭据；不会保存内存或运行进程。请求结果不确定时使用“重试原请求”，复用同一幂等标识；超过 6 天需到官方控制台核实结果。新表自动创建，无需手动迁移。

面板代码与本地协议／浏览器检查已完成；真实 Cloudflare 到 InstaBox 的桌面和快照链路仍需部署后验收。目标 VPS 的 computer-use MCP 已配置，并实测截图、输入、保存及控制权交接。模型视觉能力尚未通过：现有中转的图片请求超时，纯文本请求也出现超时，不能据此判定模型不支持图片。详见 远程桌面与 AI 接入说明 和 当前交接。

src/client/       React 页面、xterm.js 终端、noVNC 桌面、快照、本地演示
src/worker/       自动建表、登录、账号、生命周期、桌面代理、快照请求
src/shared/       前后端共享类型
migrations/       D1 数据库迁移
tests/            后端与真实 Workers 协议测试
tools/            浏览器测试、主密钥生成
wrangler.jsonc    Cloudflare 部署配置
wrangler.d1.jsonc 可选的手动 D1 迁移配置

官方依据：API keys and SDK · OpenAPI · Workers WebSockets。

图文教程

LinuxDo