# 关于 ## 开发者 [#开发者] ## 社区 [#社区] 加入我们位于 logos:telegram Telegram 的 [官方频道](https://t.me/ArcadiaPanel) 和 [交流群组](https://t.me/ArcadiaPanelGroup) ## Issue 反馈 [#issue-反馈] 请前往 [GitHub 仓库](https://github.com/SuperManito/Arcadia/issues) 提交您的问题。 我们不接受任何使用问题，这只会让你创建的 issue 被立即关闭，如果你需要获取帮助请加入社区后与社区成员进行交流。 ## 支持我们 [#支持我们] 成为赞助商享有文档广告展示，如有需求请在社区中主动联系作者，更多内容有待完善。 ## 品牌资产 [#品牌资产] Logo 和图标：[https://github.com/SuperManito/ArcadiaWebsite/tree/main/brand](https://github.com/SuperManito/ArcadiaWebsite/tree/main/brand) # 更新日志 ## `1.0.1 (2026-08-22)` [#101-2026-08-22] ### 🐛 修复 \[!toc] [#-修复-toc] * 代码同步：修复未能按预期导入定时任务的错误 ## `1.0.0 (2026-08-18)` [#100-2026-08-18] ### ✨ 新特性 \[!toc] [#-新特性-toc] * 控制面板 * 《环境配置 - 依赖管理》页面新增批量添加依赖功能 * 《个人设置 - 系统日志》页面支持一键清空日志 ### 🐛 修复 \[!toc] [#-修复-toc-1] * 前端：修复已知错误，解决部分性能问题 ## `1.0.0-beta.12 (2026-08-12)` [#100-beta12-2026-08-12] ### ✨ 新特性 \[!toc] [#-新特性-toc-1] * 控制面板 * 新增《消息中心》页面与状态栏消息提醒组件 * 《代码编辑》页面新增集成终端面板 * 《个人设置 - 通用》页面新增 “历史数据清理” 配置 * 《个人设置 - 系统日志》页面新增 “开放接口日志” 分页 * 《个人设置》页面新增 “关于” 分页，支持版本检测与更新 * 《文件管理》页面新增图标尺寸视图控制 * 运行代码文件可视化命令组件新增 “沙箱” 系列命令选项 * 文件树组件搜索不再限制于仅展开的目录，改为后端全局搜索 * 改善了各页面的初始状态界面 * 《个人设置 - 个性化》页面主题色配置新增部分内置主题色 * 大量UI设计与动效更新 * 后端服务 * 新增 “Message 消息中心” 系列 OpenAPI 接口 * 新增清理历史数据内置定时任务 * 新增版本检测与更新机制 * 提升 OpenAPI 接口响应安全性，阻止返回后端原生错误 * CLI * 运行代码文件：新增 “隔离运行（沙箱）” 系列命令选项 ### 🛠️ 优化 \[!toc] [#️-优化-toc] * 前端：优化《代码同步》页面表单格式校验 * 前端：优化《代码编辑》页面标签页行为逻辑 * 前端：优化部分组件在移动端下的行为逻辑 * 后端：优化定时任务调度引擎的回调处理逻辑 * 后端：优化文件系统与数据库错误消息处理 * 后端：重构并优化 Socket 接口配置与封装 * 后端：文件搜索结果现在敏感大小写 * 后端：优化平台服务启动链路，降低常驻内存占用 * CLI：优化依赖管理 pip 包管理器安装逻辑 * CLI：守护进程任务现在不会在重新启动时清空日志 ### 🐛 修复 \[!toc] [#-修复-toc-2] * 前端：修复了一个导致代码高亮渲染异常的问题 * 前端：修复了在 iOS 作为独立应用模式使用时未能缓存数据的问题 * 代码同步：修复私有仓库 HTTP 认证解析错误 ## `1.0.0-beta.11 (2026-06-03)` [#100-beta11-2026-06-03] ### ✨ 新特性 \[!toc] [#-新特性-toc-2] * 控制面板 * 新增《环境配置 - 依赖管理》页面 * 新增运行代码文件命令可视化组件 * 全新的文件移动组件 * 《文件管理》页新增快捷操作导航栏 * 《个人设置》页新增系统时区配置 * 新增部分代码高亮主题 * 大量UI设计与动效更新 * 代码同步 * 代码文件配置新增指定文件名称配置项 ### 🛠️ 优化 \[!toc] [#️-优化-toc-1] * 前端：优化了部分页面和组件的行为逻辑 * 后端：更换了图形验证码生成引擎并大幅提高防护强度 * 更新 TypeScript 至 V6 版本 ## `1.0.0-beta.10 (2026-04-08)` [#100-beta10-2026-04-08] ### ✨ 新特性 \[!toc] [#-新特性-toc-3] * 控制面板 * 新增《守护任务》页面，支持管理守护进程任务 * 《定时任务 - 任务配置》页支持查看运行中任务的实时输出（日志） * 大量UI设计更新 * CLI * 运行代码文件：新增 rund 子命令，移除守护运行命令选项 ### 🛠️ 优化 \[!toc] [#️-优化-toc-2] * 前端：终端现在强制深色主题 ### 🐛 修复 \[!toc] [#-修复-toc-3] * 前端：修复了在登录后未能触发上次登录提醒的问题 ## `1.0.0-beta.9 (2026-03-26)` [#100-beta9-2026-03-26] ### ✨ 新特性 \[!toc] [#-新特性-toc-4] * 控制面板 * 新增基于 Ghostty 的模拟终端，支持移动端操作 * 《环境配置 - 环境变量》页新增支持标签分类过滤，去除了标签颜色设计 * 《个人设置》页新增 “系统日志” 分页，支持查看操作日志和登录日志 * 《个人设置》页新增 “命令行” 分页，用于配置 Arcadia CLI 功能 * 《个人设置 - 令牌管理》页权限控制改为更详细的权限控制列表 * 《代码编辑》页文件树右键菜单新增 “在终端中打开” 与 “安装依赖” 功能 * 支持查看图片文件 * 后端服务 * 加强 OpenAPI 接口权限管理，改为细粒度分类控制 * 新增 “Exec 命令执行” 系列 OpenAPI 接口，支持 SSE 流式传输 * CLI * 运行代码文件：新增 Python 脚本 uv 工具集成 * 运行代码文件：新增指定 JavaScript 和 TypeScript 脚本的默认运行时配置 ### 🛠️ 优化 \[!toc] [#️-优化-toc-3] * 前端：《代码编辑》页调试运行默认不再自动保存文件内容 * 前端：《代码编辑》与《日志查询》页的文件树改为异步加载 * 前端：改善了《代码编辑》页的部分操作行为逻辑 ### 🐛 修复 \[!toc] [#-修复-toc-4] * 前端：修复了作为独立应用模式使用时未能正确同步 iOS 状态栏颜色的问题 * 后端：修复定时任务部分高级配置无效的问题 * CLI：修复在使用 “不记录日志命令” 命令选项时仍创建日志目录的问题 ## `1.0.0-beta.8 (2026-03-02)` [#100-beta8-2026-03-02] ### ✨ 新特性 \[!toc] [#-新特性-toc-5] * 前端：“个人设置 - 令牌管理” 页面新增访问权限控制，可以为指定令牌单独设置接口访问权限 * 前端：“个人设置 - 身份认证” 页面新增登出所有设备功能 ### 🐛 修复 \[!toc] [#-修复-toc-5] * 前端：修复 JS 类文件代码高亮失效的问题 * 前端：修复 “代码同步” 页面部分配置字段关联文档链接无效的问题 * CLI：修复在更新指定名称的代码同步配置时未能导入定时任务的问题 ## `1.0.0-beta.7 (2026-02-23)` [#100-beta7-2026-02-23] ### ✨ 新特性 \[!toc] [#-新特性-toc-6] * 前端：新增 “定时任务仪表盘” 页面，实现可视化浏览定时任务运行数据 * 前端：新增 “代码同步” 页面，实现可视化管理代码文件导入配置 * 前端：移除 “代码调试” 页面，其功能已合并至 “代码编辑” 页面 * 前端：“代码对比” 页面新增差异计算状态消息，以改善用户体验 * 前端：“个人设置” 身份认证页面新增双重认证配置功能 * 前端：“个人设置” 新增令牌管理分页，支持管理 OpenAPI 令牌 * 前端：“文件管理” 页面新增框选和拖拽功能，提供类似视窗文件管理器的交互体验 * 前端：“文件管理” 页面新增支持文件预览 * 前端：“文件管理” 页面批量操作新增移动端适配和下载操作 * 前端：新增适配更多文件类型图标与代码高亮 * 前端：为部分UI界面和组件添加了记忆用户选择功能 * 前端：为日志相关组件更换了新的等宽字体 * 前端：大量UI设计与动效更新 * 后端：新增项目配置系列API，用于存储项目配置 * 后端：重构登录认证架构，新增 2FA 双重认证 * 后端：重构文件目录结构与数据库封装 * 后端：强化了认证架构与文件系统整体安全性 * CLI：运行代码文件命令新增 “指定并发线程数” 命令选项 * CLI：运行代码文件命令新增 “执行参数” 命令选项 * CLI：运行代码文件命令新增 “传递选项” 命令选项 * CLI：终止代码文件命令支持终止多任务进程 * CLI：更新代码同步命令新增 “更新指定配置” 子命令 * CLI：添加代码同步配置命令完善相关命令选项 ### 🐛 修复 \[!toc] [#-修复-toc-6] * 前端：修复 “定时任务” 页面查看源码组件未按预期保存文件内容的错误 * CLI：修复代码同步配置禁用无效的问题 ### 🛠️ 优化 \[!toc] [#️-优化-toc-4] * 前端：大幅缩减前端打包体积并提高了页面加载速度 ## `1.0.0-beta.6 (2025-04-28)` [#100-beta6-2025-04-28] ### ✨ 新特性 \[!toc] [#-新特性-toc-7] * 前端：重新设计了 “定时任务” 页面查看源码组件，现在支持直接编辑 * 前端：代码编辑器工具箱新增支持语言模型选择器、内容替换按钮 * 前端：“代码对比” 页面新增差异跳转、对比互换等功能 * 前端：运行命令组件添加调整字体大小按钮 * 前端：新增 socket 连接异常弹窗提示组件，支持手动重连 * 前端：大量UI细节与动效更新 * 后端：使用 TypeScript 重构 * CLI：新增适配 Deno 和 tsx 运行环境 ### 🛠️ 优化 \[!toc] [#️-优化-toc-5] * 前端：改善了代码编辑器标签页多开功能，现在能够恢复关闭时的编辑状态 * 前端：改善了移动端编辑器键盘控制悬浮组件的展示机制与位置 * 前端：优化了代码编辑器部分功能的逻辑 * 前端：图标全量本地化，现在前端支持网络离线环境下使用 * 前端：定时任务页面 “用户” 类型更名为 “个人” * 前端：“对比工具” 页面重命名为 “代码对比” * 前端：强化移动端适配，改善交互体验 * CLI：优化了部分命令的传参路径处理，现在能更好的处理 `.` `..` `./` 等路径符号 * CLI：使用 tsx 替代 ts-node 作为默认的 TypeScript 代码文件执行器 ### 🐛 修复 \[!toc] [#-修复-toc-7] * 前端：修复了代码编辑器的一些显示错误 * CLI：修复了一些错误 ## `1.0.0-beta.5 (2024-10-16)` [#100-beta5-2024-10-16] ### ✨ 新特性 \[!toc] [#-新特性-toc-8] * 前端：“定时任务” 页面支持卡片视图 * 前端：“定时任务” 页面新增查看详情组件 * 前端：“环境变量” 与 “定时任务” 页面支持搜索内容高亮 * 前端：“代码编辑” 页面支持批量删除 * 后端：新增封装 “文件系统” 系列 OpenAPI 接口，具体详见开发者文档 * CLI：新增适配 Bun、Lua、Ruby、Rust、Perl 运行环境，前端同步适配 ### 🛠️ 优化 \[!toc] [#️-优化-toc-6] * 前端：改善了一些功能针对特定场景的工作逻辑 * 前端：改善了 “文件管理” 页面列表视图的布局 * 前端：改善了代码编辑器在移动端的使用体验 * 前端：为部分弹窗功能适配了回车确认 * 后端：重新设计了整个文件系统，调整了接口的路径、传参以及响应参数 ### 🐛 修复 \[!toc] [#-修复-toc-8] * 后端：修复了一些错误 ## `1.0.0-beta.4 (2024-09-14)` [#100-beta4-2024-09-14] ### ✨ 新特性 \[!toc] [#-新特性-toc-9] * 前端：更新了整体框架布局和大量页面以及组件的 UI 设计 * 前端：代码编辑器工具箱新增封装多个功能操作 * 前端：“定时任务” 页面编辑任务组件新增定时高级配置 * 前端：“运行日志” 页面支持轮询更新 * 前端：“运行日志” 页面支持日志反转 * 前端：“文件管理” 页面支持批量操作 * 前端：代码编辑器新增部分深色主题 * 后端：新增封装 “定时任务” 系列 OpenAPI 接口，具体详见开发者文档 * 后端：新增 “环境变量” OpenAPI 精准查询接口 * 后端：为 “环境变量” OpenAPI 查询接口添加了描述与备注字段的匹配 ### 🐛 修复 \[!toc] [#-修复-toc-9] * 后端：修复了在更新项目源码后，后端服务不符合预期自动重启的错误 * 后端：修复了一些错误 ### 🛠️ 优化 \[!toc] [#️-优化-toc-7] * 前端：提高了代码编辑器的渲染性能 * 前端：优化了静态资源的打包体积，提高了页面加载速度 * 前端：表格分页大小的用户设置支持本地存储 * 后端：优化了终止定时任务的实现逻辑 * 后端：为最近登录地理位置信息添加了局域网识别 * 后端：完善了接口响应机制 * 后端：优化了部分接口的处理逻辑，提高了性能 * CLI：调整了运行代码存储日志文件的路径 ## `1.0.0-beta.3 (2024-05-07)` [#100-beta3-2024-05-07] ### ✨ 新特性 \[!toc] [#-新特性-toc-10] * 前端：“环境变量” 复合变量值分页表格新增批量导入组件 * 前端：“环境变量” 页面表格新增更新时间字段 * 前端：UI细节更新 ## `1.0.0-beta.2 (2024-05-05)` [#100-beta2-2024-05-05] ### ✨ 新特性 \[!toc] [#-新特性-toc-11] * 后端：新增封装 “环境变量” 系列 OpenAPI 接口，具体详见开发者文档 ### 🐛 修复 \[!toc] [#-修复-toc-10] * 后端：修复了在添加新的系统定时任务后导致所有原有任务被自动删除的错误 * 后端：修复了被禁用的普通变量仍被导出的错误 * CLI：修复了一些命令的兼容性错误 * CLI：修复了一些命令选项的错误 ### 🛠️ 优化 \[!toc] [#️-优化-toc-8] * 后端：优化了批量管理系统定时任务接口的性能，提高了底层定时导入速度 ## `1.0.0-beta.1 (2024-04-28)` [#100-beta1-2024-04-28] ### ✨ 新特性 \[!toc] [#-新特性-toc-12] * 前端：新增 “环境变量” 页面，可通过表格和表单来管理用户变量数据 * 前端：全面应用了基于 TextMate 的代码语法高亮引擎，现在代码编辑器不仅更加美观还大幅提高了渲染速度，并且对于长文本解析有着出色的性能表现。 * 前端：原 “脚本管理” 页面重命名为 “文件编辑”，原 “脚本调试” 页面重命名为 “代码调试” * 前端：重新设计了 “运行日志” 和 “文件编辑” 页面的折叠侧边栏的UI交互 * 前端：“个人设置” 页面个性化分页新增自定义代码高亮主题样式配置 * 前端：“定时任务” 页面表格数据项操作列新增支持主动运行和终止运行功能 * 前端：“定时任务” 页面表格新增支持列排序，并且适配了数据项的调整排序功能 * 前端：为表格组件添加了导出数据按钮，并更新了列设置UI设计 * 前端：更新了多个页面和组件的动画效果，提升了用户体验 * 前端：为部分弹窗组件添加了全屏展示按钮 * 前端：大量UI设计更新 * 后端：重构了数据库操作封装，现在使用基于 Prisma 的 ORM 框架 * 后端：新增封装环境变量相关功能接口 * CLI：底层Shell完全重构，重新设计了项目指令，新增部分命令选项 * CLI：新增支持运行 Go 语言和 C 语言的代码文件 ### 🐛 修复 \[!toc] [#-修复-toc-11] * 前端：修复了运行日志通用组件位于标题栏的运行计时显示错误 * 前端：修复了在部分情况下编辑器需要刷新页面才能正常显示的问题 * 前端：修复了 “文件管理” 页面当文件（夹）名称过长时不符合预期的显示错误 ### 🛠️ 优化 \[!toc] [#️-优化-toc-9] * 前端：大幅提高了 “运行日志” 和 “文件编辑” 页面在移动端上的性能表现 * 前端：改进了多个页面的运行效率，优化了内存占用。 * 前端：调整了菜单选项的路由配置，现在支持右键操作 * 前端：优化了部分页面文件选择组件的交互，现在会正确处理目录节点的点击行为且不再被禁用 * 前端：优化了 “个人设置” 页面的布局 * 前端：当使用移动端书签应用时顶部系统导航栏的背景颜色现在会与主题同步 * 前端：现在编辑器组件全局默认自动换行 * 后端：代码完全重构，并配置 ESLint 统一了代码风格 * 后端：移除了旧版本的 Open API 封装接口并开始采用新的调用方式 * CLI：移除了部分无关的内容和命令 ... ## `1.0.0-alpha (2023-05-30)` [#100-alpha-2023-05-30] * 发布公测 # 环境配置 本篇介绍一些关键的用户配置 ## 用户环境变量 [#用户环境变量] 环境变量是控制代码行为的主要途径之一，平台对于配置环境变量的方式有两套设计，可以同时配置 下面具体介绍两种配置方式与基本工作原理
### 控制面板《环境配置 - 环境变量》 [#1-控制面板环境配置---环境变量] 平台对环境变量功能有着独特的功能设计，变量类型分为 **普通变量** 与 **复合变量**\ 复合变量是普通变量的高级应用，它可以将多个值分开管理最后合并成一个值，实现了更加灵活的配置以满足用户需求 该功能变量数据存储在数据库中，每次修改后都会在用户配置文件目录下自动生成 `env.sh` 批量声明脚本，以用于 CLI 命令加载
### 主配置文件 [#2-主配置文件] 主配置文件为 `config.sh`，你可以通过控制面板《环境配置 - 配置文件》进行在线编辑 首先你需要知道的是在配置文件中用 `export` 关键字声明的变量为全局变量，否则为局部变量 ```bash title="示例" export TEST_ENV="Hello World!" ``` 只有全局变量配置的信息才能被所运行的代码文件获取，局部变量一般用于控制 Arcadia 平台自身内部功能 在配置文件中声明全局环境变量是一种更加直接的底层配置方式，因为由数据库存储的另一种配置方式最终也会转换成这种形式 Arcadia CLI 先加载数据库生成的环境变量批量加载脚本 `env.sh` 再加载配置文件 `config.sh`，这意味着若存在相同变量那么会被 `config.sh` 中定义的变量覆盖
## 命令行配置 [#命令行配置] 详见面板《个人设置 - 命令行》 # 运行环境 本部分文档用于指导安装代码文件的所需运行环境，具体分为语言环境和依赖（包）环境，如果你对相关术语或技术不太熟悉那么请认真阅读以下内容 ## 安装语言环境 [#安装语言环境] skill-icons:javascript JavaScript / skill-icons:typescript TypeScript logos:python Python logos:go Go logos:lua Lua logos:ruby Ruby vscode-icons:file-type-rust Rust vscode-icons:file-type-perl Perl skill-icons:c C Bun 是一个现代的 JavaScript 和 TypeScript 运行时环境，内置包管理器，专为速度而设计，运行速度极快，并致力于兼容 Node.js API，许多 Node.js 项目可直接运行。 ```bash title="安装命令（建议分步执行以下命令）" apt-get update && apt-get install -y unzip curl -fsSL https://bun.sh/install | bash # 失败时请自行解决网络环境等问题 bash ln -sf $(which bun) /usr/local/bin/bun ``` 建议使用官方提供的默认安装方法，如果你通过其它方法安装那么需要在处理 `PATH` 时设置 `/usr/local/bin` 的软链接（参考最后一行示例命令） [官方网站](https://bun.sh) Deno 是一个现代的 JavaScript 和 TypeScript 运行时环境，具有安全性高、高性能网络等特点。默认采用沙盒机制，脚本程序需显式授予权限才能访问文件系统、网络和环境变量等敏感操作。 Deno 一般无法直接运行 Node.js 原生项目，因为它导入包（库）的语法与 Node.js 不兼容。\ 由于沙箱下的默认权限不能满足项目基本需求，因此使用 Deno 时会默认赋予一些权限，具体如下：\ · 环境变量：允许全部\ · 文件系统：仅允许读/写代码文件所在目录和其下级目录。\ · 网络访问：允许联网，但禁止访问本机 ```bash title="安装命令（建议分步执行以下命令）" apt-get update && apt-get install -y unzip curl -fsSL https://deno.land/install.sh | sh # 失败时请自行解决网络环境等问题 bash ln -sf $(which deno) /usr/local/bin/deno ``` 建议使用官方提供的默认安装方法，如果你通过其它方法安装那么需要在处理 `PATH` 时设置 `/usr/local/bin` 的软链接（参考最后一行示例命令） [官方网站](https://deno.com) TypeScript Execute (tsx) 是 Arcadia 平台关于运行 TypeScript 代码文件的默认执行器，它基于 esbuild 驱动，运行速度非常快。 npm pnpm yarn bun ```bash title="安装命令" npm install -g tsx ``` ```bash title="安装命令" pnpm add -g tsx ``` ```bash title="安装命令" yarn global add tsx ``` ```bash title="安装命令" bun add --global tsx ``` [官方网站](https://tsx.is) ts-node 是一个运行 TypeScript 代码文件的执行器，相比 tsx 它的兼容性可能会更高，不过性能会差很多。 该工具已经过时且长期未更新，不推荐使用，请优先使用 tsx npm pnpm yarn bun ```bash title="安装命令" npm install -g typescript ts-node ``` ```bash title="安装命令" pnpm add -g typescript ts-node ``` ```bash title="安装命令" yarn global add typescript ts-node ``` ```bash title="安装命令" bun add --global typescript ts-node ``` [官方网站](https://typestrong.org/ts-node) 已预装，底层功能依赖请勿卸载，否则会导致项目无法正常运行 ```bash title="安装命令" NODE_VERSION=24 # 指定安装版本（可自行修改） apt-get update && apt-get install -y ca-certificates curl gnupg curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_${NODE_VERSION}.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list apt-get update && apt-get install nodejs -y ``` Node.js 是 Arcadia 平台默认的 JavaScript 运行时环境，同时也是驱动 Arcadia 后端运行的核心依赖，默认安装的是最新的 LTS 版本，需要安装指定版本时可借鉴该命令 [官方网站](https://nodejs.org) 已预装，TG Bot 功能依赖 Python 环境运行 ```bash title="安装命令" apt-get update && apt-get install -y python3 python3-pip ``` 若你重装了其它版本，那么还需要执行 `pip3 install yq --no-cache-dir --break-system-packages` 安装 `yq` 依赖库（CLI 底层功能需要） [官方网站](https://www.python.org) uv 是一个速度极快的 Python 包和项目管理器，Arcadia 平台已适配该工具，可通过控制面板《个人设置 - 命令行》进行启用 ```bash title="安装命令" pip install uv --break-system-packages ``` 安装后可以通过 `uv python install 3.` 命令安装特定版本的 Python 运行环境，之后你可以进入到指定项目的目录通过 `uv python pin 3.` 命令将该版本 Python 固定为当前项目的运行环境 Arcadia CLI 仅适配其 `uv run` 命令来运行 Python 脚本文件，更多使用方法详见其官方文档 [官方网站](https://docs.astral.sh/uv) ```bash title="安装命令" apt-get update && apt-get install -y golang ``` 可通过控制面板《环境配置 - 依赖管理》进行安装，点击添加按钮并选择 `APT` 生态类型，包名 `golang` [官方网站](https://golang.org) ```bash title="安装命令" apt-get update && apt-get install -y lua5.4 luarocks ``` 可通过控制面板《环境配置 - 依赖管理》进行安装，点击添加按钮并选择 `APT` 生态类型，包名 `lua5.4 luarocks`（分开添加） [官方网站](https://www.lua.org) ```bash title="安装命令" apt-get update && apt-get install -y ruby ``` 可通过控制面板《环境配置 - 依赖管理》进行安装，点击添加按钮并选择 `APT` 生态类型，包名 `ruby` [官方网站](https://www.ruby-lang.org) ```bash title="安装命令（建议分步执行以下命令）" curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 失败时请自行解决网络环境等问题 bash ln -sf $(which rustc) /usr/local/bin/rustc ln -sf $(which cargo) /usr/local/bin/cargo cargo install cargo-script # 失败时请自行解决网络环境等问题 ``` 建议使用官方提供的默认安装方法，如果你通过其它方法安装那么需要在处理 `PATH` 时设置 `/usr/local/bin` 的软链接 [官方网站](https://www.rust-lang.org) 已预装，底层功能依赖请勿卸载，否则会导致项目无法正常运行 ```bash title="安装命令" apt-get update && apt-get install -y perl ``` [官方网站](https://www.perl.org) 已预装，底层功能依赖请勿卸载，否则会导致项目无法正常运行 ```bash title="安装命令" apt-get update && apt-get install -y gcc ``` ## 解决依赖 [#解决依赖] 建议优先使用控制面板《环境配置 - 依赖管理》管理全局依赖，目前支持六种包管理器，还可利用该功能安装其它包管理器或语言环境 平台目前仅内置 `npm`、`pip`、`APT`，其中 `APT` 为 Linux 系统依赖，其它包管理器需要自行安装后才可使用 skill-icons:javascript JavaScript / skill-icons:typescript TypeScript logos:python Python logos:go Go logos:lua Lua logos:ruby Ruby vscode-icons:file-type-rust Rust vscode-icons:file-type-perl Perl simple-icons:linux Linux npm pnpm yarn bun ```bash title="全局安装命令" npm install -g ``` ```bash title="全局安装命令" pnpm add -g ``` ```bash title="全局安装命令" yarn global add ``` ```bash title="全局安装命令" bun add --global ``` 适用文件类型 `.js` `.mjs` `.cjs` `.ts` `.cts` `.mts` 当运行报错提示 `Cannot find module 'xxx'` 或类似字样时，说明缺少代码运行所需的依赖。\ `xxx` 即为缺失的依赖名称，若以 `/` 开头表示本地模块文件路径，否则一般为 [logos:npm-icon NPM](https://www.npmjs.com) 上的第三方包。 `-g` 选项代表全局安装，适用于大多数场景，不使用该选项则会安装在当前项目的 `node_modules` 目录下。 可通过控制面板《环境配置 - 依赖管理》安装 `pnpm` 或 `yarn`，点击添加按钮并选择 `npm` 生态类型 pip uv ```bash title="安装命令" pip3 install --break-system-packages ``` ```bash title="安装命令" uv pip install ``` 适用文件类型 `.py` ```bash title="安装命令" go get -u ``` 适用文件类型 `.go` ```bash title="安装命令" luarocks install ``` 适用文件类型 `.lua` ```bash title="安装命令" gem install ``` 适用文件类型 `.rb` 适用文件类型 `.rs` 在 `Cargo.toml` 文件中添加依赖： ```toml [dependencies] = "" ``` 运行以下命令安装依赖： ```bash cargo build ``` 或者仅安装依赖而不构建项目： ```bash cargo check ``` 建议使用 `cpanm`，安装命令 `cpan App::cpanminus` ```bash title="安装命令" cpanm ``` 适用文件类型 `.pl` `.pm` ```bash title="安装命令" apt-get update apt-get install -y ``` 项目镜像基于 GNU/Linux Debian 构建，安装前请确认目标软件包名称是否准确\ 部分软件包名称在不同 Linux 发行版间可能存在差异，可通过 `apt search ` 命令或 [Command Not Found](https://command-not-found.com/) 搜索确认 # 什么是 Arcadia ## 名字的由来 [#名字的由来] **Arcadia** 源自希腊语 *Αρκαδία*，中文译名为 **阿卡迪亚**，它是希腊的一个二级行政区（州），位于伯罗奔尼撒半岛的中部山区，现被西方广泛引申为乌托邦，是传说中世界的中心位置，相当于中华文化中的世外桃源。 ## Arcadia 平台能做些什么 [#arcadia-平台能做些什么] Arcadia 平台面向脚本语言编程与运维场景，提供定时任务调度、多语言代码执行、完善的文件系统与底层 CLI 命令设计等能力，适用于希望借助自动化脚本提升开发运维效率的个人开发者与中小型团队。 项目基于 TypeScript 全栈开发，采用了众多前沿技术，前端使用 Vue + Vite，后端使用 Node.js + Express + Prisma ORM。 文档分为4个部分： 使用文档 命令行文档 应用程序接口文档 开放应用程序接口文档 ## 支持哪些编程语言 [#支持哪些编程语言] 已适配可直接运行代码文件的语言环境如下 | 类型 | 文件格式 | | :--------: | :-----------------: | | JavaScript | `.js` `.mjs` `.cjs` | | TypeScript | `.ts` `.mts` `.cts` | | Python | `.py` | | Go | `.go` | | Lua | `.lua` | | Rust | `.rs` | | Ruby | `.rb` | | Perl | `.pl` | | C | `.c` | | Shell | `.sh` | `Node.js` `tsx` `ts-node` `Deno` `Bun` `Python` `Go` `Rust` `Lua` `Ruby` `Perl` `C` `Shell` 平台（镜像容器）仅预装了 `Node.js` 和 `Python` 环境，其中 `Shell` 和 `C` 语言是底层运行环境直接支持的\ 其它需要用户自行安装，具体方法请前往查看 [**运行环境**](/docs/environment) # 消息通知 ## 旧版第三方渠道推送通知 [#旧版第三方渠道推送通知] 即将上线《监控告警》功能，当前内容将被废弃已不再维护，注意持续关注项目的功能变动
展开查看 用于在脚本运行后将指定内容推送到你的设备上，支持多个渠道同时推送，推送内容由脚本而定。 目前支持：Server酱、Bark、Telegram、钉钉、企业微信、iGot、pushplus、go-cqhttp、WxPusher 此功能基于底层 `sendNotify.js` 脚本实现，仅支持常见 js 脚本 编辑配置 - 下拉选择 `config.sh` - 推送通知设置区域 * ### 通知尾 \[!toc] [#通知尾-toc] ```bash export NOTIFY_TAIL="本通知 By：https://github.com/SuperManito/Arcadia" ``` 默认如上，如想修改请编辑 **config.sh** 配置文件中的变量 * ### 通知屏蔽 \[!toc] [#通知屏蔽-toc] ```bash export NOTIFY_MASKING="" ``` 变量中填写想要屏蔽的关键词，多个词用 `&` 连接，注意屏蔽针对的是内容而不是通知标题 *** ## Server酱 \[!toc] [#server酱-toc] 官网：[https://sct.ftqq.com](https://sct.ftqq.com) * SCHKEY 或 SendKey（必填） ```bash export PUSH_KEY="" ``` * 自建 Server 酱（选填） ```bash export SCKEY_WECOM="" export SCKEY_WECOM_URL="" ``` *** ## Bark \[!toc] [#bark-toc] * 设备码（必填） ```bash export BARK_PUSH="" ``` 例如 [https://api.day.app/123](https://api.day.app/123) 则填写 `123` * 声音设置（必填） ```bash export BARK_SOUND="" ``` 具体值请在bark-推送铃声-查看所有铃声，例如 `choo` * 推送消息分组 ```bash export BARK_GROUP="" ``` 默认为 `Arcadia`，推送成功后可以在`历史消息 - 右上角文件夹图标`查看 *** ## Telegram \[!toc] [#telegram-toc] 注意网络连通性问题，可能需要魔法 * token（必填） ```bash export TG_BOT_TOKEN="" ``` 填写自己申请 [@BotFather](https://t.me/BotFather) 的 Token，如 `10xxx4:AAFcqxxxxgER5uw` * user\_id（必填） ```bash export TG_USER_ID="" ``` 填写 [@getuseridbot](https://t.me/getuseridbot) 中获取到的纯数字ID * 代理设置 在配置文件中，代理相关变量已默认被注释，如需使用请自行解除注释 * 代理IP地址（选填） ```bash export TG_PROXY_HOST="" ``` 代理类型为 http，例如你的代理是 [http://127.0.0.1:1080](http://127.0.0.1:1080) 则填写 `127.0.0.1` * 代理端口（选填） ```bash export TG_PROXY_PORT="" ``` 代理类型为 http，例如你代理是 [http://127.0.0.1:1080](http://127.0.0.1:1080) 则填写 `1080` * 认证参数（选填） ```bash export TG_PROXY_AUTH="" ``` * api自建反向代理地址（选填） 参考教程：[https://www.hostloc.com/thread-805441-1-1.html](https://www.hostloc.com/thread-805441-1-1.html) ```bash export TG_API_HOST="" ``` 例如你的如反向代理地址 [http://aaa.bbb.ccc](http://aaa.bbb.ccc) 则填写 `aaa.bbb.ccc` *** ## 钉钉 \[!toc] [#钉钉-toc] 官方文档：[https://developers.dingtalk.com/document/app/custom-robot-access](https://developers.dingtalk.com/document/app/custom-robot-access) * token后面的内容（必填） ```bash export DD_BOT_TOKEN="" ``` 只需 [https://oapi.dingtalk.com/robot/send?access\_token=XXX](https://oapi.dingtalk.com/robot/send?access_token=XXX) 等号后面的 `XXX` 即可 * 密钥（必填） ```bash export DD_BOT_SECRET="" ``` 机器人安全设置页面，加签一栏下面显示的 **SEC** 开头的 **SECXXXXXXXXXX** 等字符 钉钉机器人安全设置只需勾选加签即可，其他选项不要勾选 *** ## 企业微信机器人 \[!toc] [#企业微信机器人-toc] 官方文档：[https://work.weixin.qq.com/api/doc/90000/90136/91770](https://work.weixin.qq.com/api/doc/90000/90136/91770) * 密钥（必填） ```bash export QYWX_KEY="" ``` 企业微信推送 webhook 后面的 `key` *** ## 企业微信应用 \[!toc] [#企业微信应用-toc] 参考文档：[http://note.youdao.com/s/HMiudGkb](http://note.youdao.com/s/HMiudGkb)\ ㅤㅤㅤㅤㅤ[http://note.youdao.com/noteshare?id=1a0c8aff284ad28cbd011b29b3ad0191](http://note.youdao.com/noteshare?id=1a0c8aff284ad28cbd011b29b3ad0191) * id（必填） ```bash export QYWX_AM="" ``` 素材库图片id（corpid,corpsecret,touser,agentid），素材库图片填 **0** 为图文消息, 填 **1** 为纯文本消息 *** ## iGot聚合 \[!toc] \[!toc] [#igot聚合-toc-toc] 官方文档：[https://wahao.github.io/Bark-MP-helper](https://wahao.github.io/Bark-MP-helper) * 推送key（必填） ```bash export IGOT_PUSH_KEY="" ``` 支持多方式推送，确保消息可达 *** ## pushplus \[!toc] [#pushplus-toc] 官网：[http://www.pushplus.plus](http://www.pushplus.plus) * Token（必填） ```bash export PUSH_PLUS_TOKEN="" ``` 微信扫码登录后一对一推送或一对多推送下面的 token，只填此变量默认为一对一推送 * 一对一多推送群组编码（选填） ```bash export PUSH_PLUS_USER="" ``` 一对多推送下面 -你的群组(如无则新建) -群组编码 需订阅者扫描二维码；如果你是创建群组所属人，也需点击 **查看二维码** 扫描绑定 *** ## WxPusher \[!toc] [#wxpusher-toc] 官方仓库：[https://github.com/wxpusher/wxpusher-client](https://github.com/wxpusher/wxpusher-client)\ 官方文档：[https://wxpusher.zjiecode.com/docs](https://wxpusher.zjiecode.com/docs)\ 微信公众号：WxPusher 消息推送平台 * appToken（必填） ```bash export WP_APP_TOKEN="" ``` 可在管理台查看：[https://wxpusher.zjiecode.com/admin/main/app/appToken](https://wxpusher.zjiecode.com/admin/main/app/appToken) * 微信用户的UID（选填） ```bash export WP_UIDS="" ``` 多个用户用 `;` 分隔，`WP_UIDS` 和 `WP_TOPICIDS` 可以同时填写, 也可以只填写一个 * 主题的TopicId（选填） ```bash export WP_TOPICIDS="" ``` 适用于群发，用户只需要订阅主题即可，多个主题用 `;` 分隔，使用 `WP_UIDS` 单独发送的时可以不定义此变量 * 原文链接（选填） ```bash export WP_URL="" ```
*** ## 对接消息中心 [#对接消息中心] 平台消息中心功能提供了统一的消息推送与管理，具备通知聚合能力，您可以将业务消息集中推送至此。 消息中心内置自动去重以及限流机制，消息本体支持最大字符数：`标题 200` `内容 20000`，超出部分将被截断。 ````mdx title="消息内容支持 Markdown 语法（自动识别）" # 标题（支持 1-6 级） ## 二级标题 **加粗文本** 和 *斜体文本* - 无序列表项 - 另一项 1. 有序列表 2. 第二项 [链接文本](https://example.com) ![图片描述](https://example.com/image.png) ![自定义尺寸](https://example.com/image.png =200x100) `行内代码` ```bash // 代码块（支持语言高亮） echo "Hello, World!" ``` > 引用文本 | 表头 | 表头 | | :-: | --- | | 内容 | 内容 | ````
消息渲染效果测试脚本（展开查看） ```javascript const message = require('/arcadia/src/utils/message-sdk') !(async () => { console.log(await message.push('渲染测试', `# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 正文段落：这是一段普通文本，包含 **加粗**、*斜体*、~~删除线~~ 和 \`行内代码\` 等行内样式。行内代码示例如 \`npm install\`、\`pnpm dev\` 等命令。 第二段文本。段落之间应有适当的垂直间距。 ## 链接与图片 外部链接：[Arcadia 官网](https://arcadia.cool) 不可点击链接（安全策略）：[锚点链接](#section) 和 [相对路径](./page) 图片（外部 URL）： ![示例图片](https://cdn.jsdelivr.net/gh/SuperManito/ArcadiaWebsite@main/brand/arcadia-pure-logo.png) ## 引用块 > 这是一段引用文本。 > 引用可以跨多行。 > > 引用内也可以有 **加粗** 和 \`行内代码\`。 ## 列表 无序列表： - 项目一 - 项目二 - 子项目 2.1 - 子项目 2.2 - 项目三 有序列表： 1. 第一步：安装依赖 2. 第二步：配置环境 3. 第三步：启动服务 任务列表： - [x] 已完成任务 - [ ] 未完成任务 - [x] 另一个已完成的任务 ## 表格 | 左对齐 | 居中对齐 | 右对齐 | | :----- | :------: | -----: | | 单元格1 | 单元格2 | 单元格3 | | 长文本内容 | 更多内容 | 数值123 | | \`代码\` | [链接](https://example.com) | **加粗** | ## 代码块 无语言代码块（纯文本渲染）： \`\`\` 这是普通代码块 可以包含多行 不会进行语法高亮 \`\`\` 带语言标识的代码块（语法高亮）： \`\`\`javascript function greet(name) { console.log(\`Hello, \${name}!\`); } greet('World'); \`\`\` Shell 代码块： \`\`\`shell cd /path/to/project npm install npm run dev \`\`\` ## 分割线 --- 分割线上方的内容与下方的内容应有较大间距（2em）。 ## 嵌套与混合 1. 有序列表第一项 - 嵌套无序子项 A - 嵌套无序子项 B 2. 有序列表第二项 > 嵌套引用块内容 结束。`)) })() ``` > 直接在 Aradia 平台上创建脚本并复制粘贴后运行即可
* ### SDK [#sdk] SDK 位于项目 `src/utils/message-sdk` 目录下，零外部依赖，仅支持本地环境调用。 Node.js (ESM) Node.js (CommonJS) ```javascript async function sendArcadiaMessage(title, content, type = 'info') { try { const { push } = await import('/arcadia/src/utils/message-sdk') await push(title, content, type) } catch (error) { console.error('推送消息失败：', error) } } // 推送 info 类型消息（默认） await sendArcadiaMessage('备份完成', '数据库备份已成功完成') // 推送 success 类型消息 await sendArcadiaMessage('版本更新', 'v2.1.0 已发布', 'success') ``` ```javascript async function sendArcadiaMessage(title, content, type = 'info') { try { const { push } = require('/arcadia/src/utils/message-sdk') await push(title, content, type) } catch (error) { console.error('推送消息失败：', error) } } !(async () => { // 推送 info 类型消息（默认） await sendArcadiaMessage('备份完成', '数据库备份已成功完成') // 推送 success 类型消息 await sendArcadiaMessage('版本更新', 'v2.1.0 已发布', 'success') })() ``` 调用导出方法 `push(title, content, type)` | 参数 | 必填 | 说明 | | ------- | -- | -------------------------------------------------- | | title | 是 | 消息标题 | | content | 是 | 消息内容 | | type | 否 | 消息类型，默认 `info`，可选值：`info`、`warn`、`error`、`success` | 返回值：推送成功返回 true，推送失败抛出 Error 其它语言建议使用下方的本地 HTTP 请求方式 * ### HTTP 请求 [#http-请求] * #### API [#api] 内部接口，仅支持本地调用，无认证，与 SDK 的工作原理相同 基准地址：`http://127.0.0.1:5678` /api/inner/message/push * #### OpenAPI [#openapi] 详见 [Message 消息中心 - 推送消息](/docs/openapi/message/v1-create-post) * ### CLI（命令行） [#cli命令行] 详见 [CLI - 推送通知](/docs/cli/sundry/notify) # 控制面板 默认通过 `http://localhost:5678` 访问，如若更改了面板服务的主机映射端口则需要访问对应端口 用于登录的初始用户名和密码分别为 `useradmin` `passwd`，登录后请按照引导提示尽快修改认证信息。 ## 浏览器限制 [#浏览器限制] 由于使用了较新的技术，一些旧版本的浏览器可能存在兼容性问题。建议使用 Chromium 内核的64位浏览器如 Chrome、Edge 等，并且不建议使用 FireFox 等其它内核的浏览器。 在 simple-icons:apple Apple 设备上使用时，`iOS / iPadOS` 最低需要 `16.4` （不支持2023年4月以前的版本使用），`macOS` 受到的影响较小 ## 在移动端使用 [#在移动端使用] 前端控制面板对移动端进行了深度适配，推荐以**独立应用模式**使用，能达到原生应用级的流畅体验，具体配置方法如下： * 以 simple-icons:apple iOS 为例，打开 logos:safari Safari 浏览器并访问 Arcadia 登录页面（注：不要登录），点击 material-symbols:ios-share **分享**，然后分别点击 `查看更多 - 添加到主屏幕`。 注意部分系统的浏览器会锁定 60fps，因此相较于在高刷新率屏幕场景下使用时观感和体验会有所差异。苹果 Safari 浏览器默认限制 60fps，推荐启用高帧率模式（启用方法详见下方）。 苹果设备默认启用 ProMotion 自适应高刷，Safari 浏览器默认限制在了 60fps，以 iOS 为例具体启用方法详见下方，如果你的设备不支持高刷那么请直接忽略 `设置 APP` > `App` > 下滑找到 `Safari 浏览器` > 滑至底部点击 `高级` > `功能开关` > 下滑找到 `Prefer Page Rendering Updates Near 60fps` 关闭。 ## 常见问题 [#常见问题] 在不重新部署的情况下更改面板映射端口 请在宿主机执行下面的命令 * 1. 进入相关目录 ```bash cd /var/lib/docker/containers/$(docker inspect --format='{{.Id}}' arcadia) ``` 容器名默认为 `arcadia` ，如果不是则自行修改 * 2. 一键修改配置文件 ```bash sed -i "s/HostPort.*\}\]\},/\"HostPort\":\"5678\"\}\]\},/g" hostconfig.json ``` 将命令中的 `5678` 替换成新的端口号即可 * 3. 重启 Docker 服务 ```bash systemctl restart docker ``` 如果你需要通过域名使用建议使用反向代理，这里以 `nginx` 为例 ```nginx server { listen 80; listen 443 ssl; // highlight-next-line server_name <域名>; // highlight-next-line ssl_certificate <证书文件路径（crt）>; // highlight-next-line ssl_certificate_key <证书私钥路径（crt）>; location / { // highlight-next-line proxy_pass http://127.0.0.1:5678; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } ``` 详见 CLI 文档部分 [重置登录信息](/docs/cli/server/service#重置登录信息) 最新编译后的前端代码在仓库 `public` 目录下，你可以自行本地部署 WEB 服务 通过修改 `app.config.js` 文件中的 VITE\_GLOB\_API\_URL 和 VITE\_GLOB\_WS\_URL 来指定后端服务地址： `"VITE_GLOB_API_URL":"http://localhost:5678/api"`\ `"VITE_GLOB_WS_URL":"ws://localhost:5678"` # 快速开始 本项目依托容器技术需要安装相关容器服务才可以部署，由于运行环境复杂程度较高目前没有计划适配更多部署方式\ 关于部署 Arcadia 平台所需要的最低配置：`2GB` 磁盘空闲、`256MB` 内存，不支持 ARMv6 / ARMv7
## 启动容器 [#启动容器-step] 1. 点击右侧的 “高级配置” 可以自定义参数配置，建议优先通过该组件修改命令以防出错 2. 提示 `-bash: docker：Command not found/未找到命令` ? 请阅读下方 *“如何安装 Docker”* 3. 不可以更改参数中 `:` 右边的内容，否则会导致后端服务无法正常访问 4. 不建议部署在 `host` 网络模式下（会暴露内部服务且不需要鉴权），除非你能够始终隔离在受控局域网内使用，严禁公网转发 simple-icons:linux Linux mage:microsoft-windows Windows simple-icons:apple macOS ```bash bash <(curl -sSL https://linuxmirrors.cn/docker.sh) ``` 该一键脚本由本项目作者开发，如果你觉得脚本好用麻烦送颗星⭐ 建议使用 [**Docker Desktop**](https://docs.docker.com/desktop/windows/install) 建议使用 [**Docker Desktop**](https://docs.docker.com/desktop/mac/install)，支持 Apple Silicon 芯片 容器挂载目录的作用是将宿主机的文件系统目录或文件挂载到容器内部。挂载后，容器内的程序可以像访问本地文件一样访问这些文件或目录，同时宿主机上的应用也可直接对其进行操作。这种机制实现了容器与宿主机之间的文件共享，使得数据持久化成为可能——即使容器被删除，挂载的数据仍保留在宿主机上，便于后续迁移或复用。 命令中的 `--cap-add SYS_PTRACE` 是[沙箱功能](/docs/cli/script/run/sandbox)的必要配置项，使沙箱能够获得进程追踪的能力。 该参数不会影响宿主机安全性，如果不使用沙箱功能可从命令中将其移除。 当前底层镜像基于 `GNU/Linux Debian` 构建，因此 Arcadia 平台镜像的占用空间达到了 1.1GB。在不更换底层构建镜像的前提下，已对镜像大小进行了最大程度的压缩。考虑到实际使用环境的生态多样性，这是权衡利弊后的决策选择。实际使用过程中会安装较多依赖内容，届时镜像大小的差异与容器总体占用空间的差异相比，影响已相对有限，建议预留 2GB 的空间以供使用。
## 开始使用 [#开始使用-step] 访问 [http://localhost:5678](http://localhost:5678) 进入控制面板 初始用户名和密码分别是 `useradmin` `passwd`，首次登录后会引导你修改此认证信息。 若无法访问请详见下方排除故障指南，希望对你有所帮助。
## 常见问题 [#常见问题-step] 下面是解决步骤顺序和思路，请按顺序进行逐一排查 * 检查容器运行状态，是否启动正常并初始化成功 查看容器状态（宿主机） ```bash docker ps -a ``` 查看容器初始化日志（宿主机） ```bash docker logs -f arcadia ``` 当输出 `Arcadia service is ready` 字样后即可通过 `Ctrl + C` 退出查看\ 如果报错导致容器没有启动成功那么请先自查原因，绝大多数问题都是由网络环境导致，你可以在 [社区](/docs/about#社区) 内寻求帮助 目前容器会在启动时自动更新 Arcadia 源代码（注：非强制等待，有超时机制），为了确保你能够使用最新的版本如果查看到日志显示更新失败请 [手动更新](/docs/update#更新源码) * 检查面板服务状态，查看有无报错并进行验证 查看服务状态（容器环境） ```bash pm2 status arcadia_server ``` 查看服务日志（容器环境） ```bash pm2 logs arcadia_server ``` 查看网页内容（容器环境） ```bash curl 127.0.0.1:5678/auth ``` 执行完此命令后如果有网页内容则表示服务启动正常 * 检查网络连通性 若你使用 **VPS** 平台，请进入你所使用平台提供商的网络防火墙功能设置，检查是否已放开相关端口、允许`HTTP/HTTPS`流量通过等重要设置 ```bash ping xxx nslookup xxx curl xxx ``` 1. 在容器内通过 `curl` 命令能获取到网页元素证明服务正常 2. 在客户端通过 `ping` 命令不能获取到返回值证明存在网络连通性问题 3. 在宿主机通过 `curl` 命令能获取到网页元素证明容器正常 4. 在客户端通过 `curl` 命令不能获取到网页元素证明可能有防火墙介入 运行代码文件是 Arcadia 平台的核心功能之一，此部分内容与平台 CLI 命令行设计紧密相连，具体详见[《运行代码文件（脚本）》](/docs/cli/script/run) 定时任务功能是 Arcadia 平台的核心功能之一，定时任务会运行任务配置中的 Shell 命令，不强制关联代码文件。 其中系统类型的任务由[代码同步](/docs/sync)功能自动管理，你可以通过代码同步功能中的 `cronSettings - 定时任务配置` 来实现自动导入运行目标代码文件的定时任务。 具体请详见[《代码同步》](/docs/sync)，代码同步功能是 Arcadia 平台用于导入代码（文件）的统称，目前支持 “代码仓库” 与 “代码文件” 两种类型并提供丰富的功能性配置。 如果你想**自动更新**代码同步功能中订阅的仓库以及代码文件（脚本），请在控制面板《定时任务》页面创建 `arcadia update` 个人任务 系统内置了一个自动清理历史数据的定时任务，你可以在控制面板《个人设置 - 通用》页面进行自定义配置。该任务属于内置定时任务，独立于用户定时任务管理体系，因此你无法在控制面板《定时任务》页面看到它。 如果你想了解的是如何清理代码文件运行日志，详见[《CLI - 清理日志》](/docs/cli/sundry/rmlog)，清理代码文件运行日志是上方所提到的自动清理历史数据的一部分，因此不用手动操作。 详见[《在移动端使用》](/docs/panel#在移动端使用)
# 更新升级 本部分文档用于指导更新 Arcadia 和容器镜像，如果你想了解的是如何更新导入的代码文件，那么请前往查看 [CLI 文档](/docs/cli/update/upgrade)。 ## 更新方式 [#更新方式] | 方式 | 说明 | | ---- | ----------------------------------------------- | | 控制面板 | 在《个人设置 - 关于》页面一键检查更新 | | CLI | 详见 [CLI - 更新 Arcadia](/docs/cli/update/upgrade) | 如果您的网络环境不稳定，建议在 CLI 中进行更新以便能够更好的排查问题 * ### 更新原理 \[!toc] [#更新原理-toc] Arcadia 平台更新基于 Git 从远程仓库拉取最新源码，因此环境需要能够访问 GitHub 才能更新，如果环境不能有效连通 GitHub 可参考下方的设置代理方法。
使用免费代理进行更新（展开查看） ```bash title="配置 GitHub Proxy 免费代理" # 进入 Arcadia 源码目录 cd /arcadia/src # 将远程仓库地址指向代理地址 git remote set-url origin https://ghfast.top/https://github.com/SuperManito/Arcadia.git # 返回用户根目录 cd /arcadia ``` 之后就可以正常更新了，不用每次更新时都重复配置一遍 代理可能会不稳定，若更新失败请再次尝试或自行更换代理。注意代理来源的安全性，避免使用不明来源的代理。
如果部署在离线环境中那么请通过[更新镜像以及容器](#更新镜像以及容器)的方式进行更新 * ### 版本号设计 \[!toc] [#版本号设计-toc] 版本号格式为 `x.xx.xx`，由三部分构成： * 主版本号：大版本更新，可能存在破坏性变更，更新前请阅读更新日志 * 次版本号：视更新日志要求而定，一般直接更新源码即可 * 修订版本号：小版本更新，直接更新源码即可，无需重新部署 * ### 更新期间注意事项 \[!toc] [#更新期间注意事项-toc] * 更新期间请勿干预，等待更新完成后再操作 * 更新完成后服务可能自动重启，面板页面可能短暂断开，属于正常现象 * 若更新完成后服务长时间未恢复，请在终端中执行 `ad service start` 重新启动服务并自查原因 ## 更新镜像以及容器 [#更新镜像以及容器] 由于平台特性导致容器镜像体积较大，因此本项目不会频繁发布新镜像 ```bash title="删除旧容器和镜像" docker rm -f arcadia docker rmi supermanito/arcadia ``` 删除旧容器和镜像不会丢失用户数据，代码运行环境除外，之后请前往查看[《安装文档》](/docs/quick-start)重新安装 Arcadia 即可 如果你有在控制面板《环境配置 - 依赖管理》配置全局依赖，那么可以使用该页面提供的 ”一键安装“ 功能自动补全环境。 ## 切换至测试版 \[!toc] [#切换至测试版-toc]
一键切换脚本（展开查看） ```bash #!/bin/bash cd /arcadia/src git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" current="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)" if [[ "$current" != "dev" ]]; then echo -e "\n正在切换分支，可能会消耗较长时间用于下载，请耐心等待...\n" fi git fetch origin if [[ "$current" == "dev" ]]; then git checkout -f -B main origin/main echo -e "\n已切换回用户版本\n" else git checkout -f -B dev origin/dev echo -e "\n已为您切换至开发版本，感谢参与测试\n" fi pm2 delete arcadia_server >/dev/null 2>&1 || true ad service start ``` 开发环境可能会不稳定，若无特殊需求请勿切换至开发环境，若切换后出现问题请重复运行本脚本切换回生产分支。
# 概述 ## 接口基准地址 [#接口基准地址] `http://localhost:5678/api` ## 接口鉴权 [#接口鉴权] 在 Header 中添加 `Authorization` 字段，值为 `Bearer {Token}` 关于如何获取 `Token` 详见登录认证接口详见 [登录认证接口](/docs/api/user/auth) ## 响应状态码说明 [#响应状态码说明] | 状态码 | 含义 | 说明 | | :---: | :-------------------: | :-----------: | | `200` | OK | 请求成功 | | `400` | BAD REQUEST | 请求格式错误、参数校验失败 | | `401` | UNAUTHORIZED | 未提供授权信息 | | `403` | FORBIDDEN | 认证失败 | | `500` | INTERNAL SERVER ERROR | 内部错误 | ## 返回内容格式 [#返回内容格式] 数据返回格式统一使用 JSON ## 业务代码说明 [#业务代码说明] | 状态码 | 说明 | | :---: | :-----: | | `0` | 请求失败 | | `1` | 请求成功 | | `400` | 接口不存在 | | `401` | 未提供授权信息 | | `403` | 认证失败 | | `500` | 服务器内部错误 | ## 参数传递 [#参数传递] 除 GET 请求通过 URL 传递参数外，其它请求方式均通过 Body 传递参数 ## WebSocket 接口 [#websocket-接口] 基准地址 * `ws://localhost:5678` 鉴权方式与 HTTP 接口相同 目前有三个接口 * `/api/ws` 默认通用 * `/api/ws/terminal` 终端服务 * `/api/ws/daemon-log` 守护任务实时日志 ## 接口类别 [#接口类别] # 概述 ## 基础 [#基础] 核心入口指令为 `arcadia`，下面是命令帮助菜单，你可以在使用中随时输入 `arcadia` 查看帮助菜单 为了便于用户操作，项目环境设置了一个简短的重定向指令 `ad` ```sh title="$ arcadia" ❖ Arcadia CLI 运行代码相关 run 运行代码文件 rund 运行代码文件（守护进程） stop 终止运行中的代码程序（脚本） list 列出指定目录下可执行的代码文件清单 ps 查看资源消耗和运行中的代码进程 cleanup 终止阻塞的代码进程，释放内存 更新与升级 update 更新代码同步配置 upgrade 更新项目源码，升级版本 用户配置管理 repo 导入代码仓库配置 raw 导入代码文件配置 envm 管理环境变量数据 服务管理 service 项目后端服务 tgbot 电报机器人 其它 rmlog 清理运行日志文件 notify 推送自定义通知消息 ``` 其中涉及到 `` 的子命令是需要进一步传入参数而不能单独执行的，具体请看子命令的帮助菜单和其它部分的文档内容 另外在接下来的文档内容和命令帮助菜单中，你会看到很多由括号括起来的内容，这些是需要你自行输入的内容或可选命令 比如： * `` 表示需要你自行输入与命令相关的内容，`` 则表示支持多种类型的内容 * `` 表示固定的子命令或传参，分别表示对应命令的不同功能实现 * `[xxx]` 表示可选的内容，一般是命令选项，分别对应命令的不同可选功能扩展 方括号和尖括号均作为指导用户输入的提示，不必传入 ## 执行命令的位置 [#执行命令的位置] 执行位置区分容器内、容器外这一基础概念性问题，容器外即表示宿主机，由于项目运行在容器内，所以不能直接在宿主机执行相关命令，可通过如下两种方式实现 * ### 进入容器内 [#进入容器内] ```bash docker exec -it <容器名称/容器ID> bash ``` 控制面板中的命令行界面就是在容器内操作的 * ### 在宿主机调用 [#在宿主机调用] ```bash docker exec -it <容器名称/容器ID> bash <命令> ``` 执行复杂命令建议使用 `docker exec -it <容器名称/容器ID> bash -c "<命令>"`，多个命令需用 `;` 或 `&&` 连接即 `"<命令> && <命令>"` 后者 `&&` 表示前一条命令执行成功时再执行后一条命令，否则遇到报错会中断，相比前者用法较为特殊 # 概述 可下载并导入到 Postman / Apifox 等 API 工具中使用 官方外部文档 ## 接口基准地址 [#接口基准地址] `http://localhost:5678/api/open` 服务端已开启 CORS 跨域支持 ## 需要授权 [#需要授权] 需要在 **请求头（Header）** 或 **请求地址参数（URL）** 中携带 `api-token` 字段并提供授权令牌，建议优先在请求头中携带 关于如何创建和管理该令牌请前往面板《个人设置 - 令牌管理》页面 ## 权限控制 [#权限控制] 令牌可以单独设置访问权限，接口会根据令牌的权限来限制访问，关于权限说明详见[此处](/docs/api/token/permission) ## 安全的操作 [#安全的操作] 接口封装方法都经过了严格的设计以确保操作的安全性\ 接口会对请求传参进行严格的格式校验，一般不会响应原生错误信息 ## 返回内容格式 [#返回内容格式] 数据返回格式统一使用 JSON | 名称 | 类型 | 描述 | | :-------: | :------------------------------------------------------: | --------- | | `code` | `number<0 \| 1 \| 4400 \| 4401 \| 4403 \| 4404 \| 4405>` | 业务代码，详见下方 | | `message` | `string` | 消息 | | `type` | `string` | 类型 | | `result` | `boolean \| object \| string` | 结果 | ## 业务代码说明 [#业务代码说明] | 状态码 | 含义 | 说明 | | :----: | :---------------: | :----------------: | | `0` | OK | 请求成功 | | `1` | FAIL | 请求失败 | | `4400` | BAD REQUEST | 请求的地址不存在或者包含不支持的参数 | | `4401` | UNAUTHORIZED | 未提供授权信息 | | `4403` | FORBIDDEN | 认证失败 | | `4404` | NOT FOUND | 路径不存在 | | `4405` | PERMISSION DENIED | 权限不足 | ## 编程接口 [#编程接口] 基准地址 `http://localhost:5678/api/open/extra` 后端使用 [logos-nodejs-icon Node.js](https://nodejs.org) 搭建，所以如果你想使用这个功能则需要会写一些 JavaScript 代码 将代码存放在 **config** 目录下的 `extra_server.js` 脚本中（自行创建），[重启服务](/docs/cli/server/service#开启重启服务)后生效，注意届时检查日志进行确认\ 脚本需要导出唯一函数名，已固定函数传参详见下方示例，接口服务框架采用 [Express v5](https://expressjs.com)，更多编写方法请查阅其文档 请参考下方的简单示例
点此展开查看代码示例 ```js title="extra_server.js" lineNumbers async function Main(api, resTemplate, logger) { // api express框架实例 // resTemplate 接口响应内置模板（具体详见 src/backend/api/model.ts，也可以自定义） // logger 日志组件，支持分级（info、warn、debug、error、fatal），之后你可以在 server.log 中查看 api.get('/test1', function (request, response) { // queryParams = request.query try { const msg = '/api/open/extra/test1 GET 接口请求成功' response.send(resTemplate.okData(msg)) // 请求成功 logger.info(msg) } catch (e) { response.send(resTemplate.fail(e.message)) // 请求失败 } }) api.post('/test2', function (request, response) { // bodyParams = request.body try { const msg = '/api/open/extra/test2 POST 接口请求成功' response.send(resTemplate.okData(msg)) // 请求成功 logger.info(msg) } catch (e) { response.send(resTemplate.fail(e.message)) // 请求失败 } }) } module.exports = Main ```
## 接口类别 [#接口类别] # 代码同步 代码同步是 Arcadia 平台用于导入代码（文件）的功能统称，核心配置文件为 `/arcadia/config/sync.yaml`，建议通过控制面板《环境配置 - 代码同步》页面进行可视化编辑与使用，本部分文档主要介绍配置方法与各字段含义 > 如果你想导入本地代码文件那么直接上传至 `/arcadia/scripts` 目录下即可 ## 关于定时任务 [#关于定时任务] 对于定时任务功能平台有专门的前端管理页面，可进行可视化操作，目前设计了两个功能板块（标签页） 一个是基于 `sync.yaml` 用户代码同步配置所自动管理的 “系统任务”，另一个是用户自定义的 “个人任务” * 系统任务则会在执行 `arcadia update` 更新代码同步配置命令时动态添加或删除，具体如下： 定时规则优先从代码文件（注释）内容中获取，由强大的算法提供支持会自动检索识别并进行语法格式校验，如若未识别到或检测到语法错误，届时会随机生成一个每天执行一次的定时规则，你可以在自动添加定时任务之后使用控制面板来自定义修改 自动添加的定时任务命令为 `arcadia run xxx`，没有附加任何命令选项，更多用法详见 [CLI 文档教程](/docs/cli/script/run) 定时任务不会重复添加，不过在特殊环境下新增的定时任务会直接覆盖原有的定时任务，例如在迁移后的环境或重新克隆了仓库 # TG Bot ## 配置方法 [#配置方法] 编辑配置 - 下拉选择 `bot.json` ```json { "//": "//开头的都是注释，勿动，剩下的按要求自行更改", "//user_id": "↓↓↓ 你的USERID，去除双引号 ↓↓↓", "user_id": 123456789, "//bot_token": "↓↓↓ 你的机器人TOKEN ↓↓↓", "bot_token": "123456789:ABCDEFGSHSFDASDFAD", "//api_id": "↓↓↓ https://my.telegram.org 在该网站申请到的id ↓↓↓", "api_id": "456423156", "//api_hash": "↓↓↓ https://my.telegram.org 在该网站申请到的hash ↓↓↓", "api_hash": "ASDFAWEFADSFAWEFDSFASFD", "//proxy": "↓↓↓ 使用代理改成true，不使用下方带proxy的不用动 ↓↓↓", "proxy": false, "//proxy_type": "↓↓↓ socks5 或者 http 或者 MTProxy ↓↓↓", "proxy_type": "socks5", "//proxy_add": "↓↓↓ 代理IP地址例如：192.168.99.100 ↓↓↓", "proxy_add": "192.168.99.100", "//proxy_port": "↓↓↓ 代理端口，不需要双引号例如 5890 ↓↓↓", "proxy_port": 5890, "//proxy_secret": "↓↓↓ 如果使用MTProxy，填入MTProxy代理秘钥 ↓↓↓", "proxy_secret": "", "//proxy_user": "↓↓↓ 代理的username,有就改，没有就不要动 ↓↓↓", "proxy_user": "代理的username,有则填写，无则不用动", "//proxy_password": "↓↓↓ 代理的密码,有则填写，无则不用动 ↓↓↓", "proxy_password": "代理的密码,有则填写，无则不用动", "//StartCMD": "↓↓↓ 是否开启CMD命令，开启改成true ↓↓↓", "StartCMD": false, "//noretry": "↓↓↓ 是否 关闭 bot掉线重连，默认开启，关闭改成true ↓↓↓", "noretry": false } ``` 必须至少正确配置前 `4` 个关键参数才可以使用，同时强烈建议开启CMD命令（倒数第二个） 每次修改配置后下次启动服务后才能够生效，非立即生效 *** 下面是配置获取教程👇
## 获取用户ID [#1-获取用户id] * 打开 Telegram 搜索 `@WuMingv2Bot` 或[点击此处](https://t.me/WuMingv2Bot)前往，输入 `/id` 获取
## 创建BOT [#2-创建bot] * 打开 Telegram 搜索 `@BotFather` 或[点击此处](https://t.me/BotFather)前往，输入 `/newbot` 按提示创建一个新的 Bot create_bot 如图，将获取到的 `bot_token` 填入 **bot.json** 中
## 获取API [#3-获取api] * 请使用美国原生节点(其它地区不行)打开网址 [https://my.telegram.org](https://my.telegram.org)，输入你注册 Telegram 时的手机号进行登录 * 点击登录后会给你的 Telegram 账号发送一条含有验证码的消息(不是短信)，登录后点击 `API development tools` ，随意瞎填即可 create_application * 下面是创建完的截图，将获取到的 `api_id` 和 `api_hash` 填入 **bot.json** 完成配置 create_application * 服务启动后如果网络正常，那么会自动给你发送一条消息，表明已经建立了连接 ***
## 代理设置（可选） [#代理设置可选] 如果容器环境本身不支持访问外网那么需要配合代理才能使用，`MTProxy` 代理效果不佳，推荐使用 `Socks5` **Socks5** 代理特征明显容易被墙，**强烈建议** 配合 **IP限制策略** 使用，即配置服务端口仅允许你设备的流量通过 * 一台能够访问 Telegram 服务的设备，通过 CLI 一键启动 **Socks5** 代理容器 ```bash {2-4} docker run -d -p <自定义端口号>:1080 \ -e PROXY_USER=<自定义用户名> \ -e PROXY_PASSWORD=<自定义密码> \ -e PROXY_SERVER=0.0.0.0:1080 \ --name socks5 \ --restart always \ xkuma/socks5 ``` * 分别对应 ```json { "proxy": true, "proxy_type": "socks5", "proxy_add": "<你的服务器IP地址>", "proxy_port": <你的端口号>, "proxy_user": "<你的用户名>", "proxy_password": "<你的密码>", } ``` # Captcha 验证码 用于认证登录，该系列接口不参与鉴权 ## 获取验证码图片 [#获取验证码图片] /captcha ### 请求 [#请求] ## 判断是否需要提供验证码 [#判断是否需要提供验证码] /captcha/flag ### 请求 [#请求-1] 无参数 ### 响应 [#响应] ```json title="示例" { "showCaptcha": false } ``` # CLI 配置 ## 获取 CLI 配置 [#获取-cli-配置] /config/cli ### 响应 [#响应] ```json title="示例" { "REMOVE_LOG_DAYS_AGO": "7", "ENABLE_UPDATE_EXTRA": "", "ENABLE_UPDATE_EXTRA_SYNC_FILE": "", "UPDATE_EXTRA_SYNC_FILE_URL": "", "ENABLE_INIT_EXTRA": "", "ENABLE_TASK_BEFORE_EXTRA": "", "ENABLE_TASK_AFTER_EXTRA": "", "ENABLE_AUTO_DELETE_REMOTE_FILE": "", "ENABLE_CUSTOM_NOTIFY": "", "RUN_DELAY_MAX_SECONDS": "300", "DEFAULT_JS_RUNTIME": "node", "DEFAULT_TS_RUNTIME": "tsx", "ENABLE_PYTHON_UV": "" } ``` *** ## 更新 CLI 配置 [#更新-cli-配置] /config/cli 支持部分字段更新，仅传入需要修改的字段即可。保存成功后自动重新生成 `.arcadia_cli_config.sh` 配置批量声明脚本。 ### 请求 [#请求] ```json title="示例" { "ENABLE_UPDATE_EXTRA": "true" } ``` ### 响应 [#响应-1] 无数据，仅返回操作状态。 CLI 配置统一存储于数据库 `config` 表（`module = 'cli'`）中，键名为去除 `CLI_CONFIG_` 前缀的字段名。每次保存后自动生成位于用户配置文件目录下的 `.arcadia_cli_config.sh` 脚本，该脚本会在底层 Shell 命令执行时自动加载。 # Config 配置管理 # 数据关系模型 配置数据统一存储于数据库 `config` 表中，通过 `key` + `module` 唯一键区分不同配置项。\ `module` 对应配置模块枚举：`runtime`（运行时）、`user`（用户认证）、`cli`（CLI 配置）、`system`（系统全局配置）。 ```prisma model config { id Int @id @default(autoincrement()) key String module String @default("runtime") value String @default("") create_time DateTime @default(now()) update_time DateTime @default(now()) @updatedAt @@unique([key, module]) @@index([module]) } ``` 所有配置值均以字符串形式存储（`value` 字段），读取时由业务层按需转换类型。 ## 系统配置（system） [#系统配置system] 通过 `/config/system` 接口读写，内部存储键为 camelCase。 | 字段 | 说明 | 用途 | | -------------------------- | ------------------------------------ | ------------------ | | `timezone` | IANA 时区标识符，默认 `Asia/Shanghai` | 《个人设置 - 通用》环境配置 | | `npmRegistry` | npm/pnpm 镜像源地址，留空使用官方源 | 《依赖管理》软件源配置 | | `pipIndexUrl` | pip index-url，留空使用 PyPI 官方源 | 《依赖管理》软件源配置 | | `aptMirrorUrl` | APT 镜像源根路径，留空使用官方源 | 《依赖管理》软件源配置 | | `gemRegistry` | RubyGems 镜像源地址，留空使用官方源 | 《依赖管理》软件源配置 | | `logRetentionDays` | 系统日志保留天数，默认 `7` | 《个人设置 - 通用》 历史数据清理 | | `messageRetentionDays` | 消息中心已读消息保留天数，默认 `7` | 《个人设置 - 通用》 历史数据清理 | | `taskHistoryRetentionDays` | 定时任务执行统计数据保留天数，默认 `7` | 《个人设置 - 通用》 历史数据清理 | | `cleanupCronExpression` | 定时清理任务 cron 表达式，为空时自动生成每日执行 | 《个人设置 - 通用》 历史数据清理 | | `cleanupCronEnabled` | 是否启用定时清理任务，`true` 启用 `false` 禁用，默认启用 | 《个人设置 - 通用》 历史数据清理 | ## CLI 配置（cli） [#cli-配置cli] 通过 `/config/cli` 接口读写，保存后自动生成 `.arcadia_cli_config.sh` 供 Shell 命令加载。 | 字段 | 说明 | 用途 | | -------------------------------- | ---------------------------------------------------------------------- | ----------------- | | `REMOVE_LOG_DAYS_AGO` | 代码文件运行日志保留天数（`arcadia rmlog`），默认 `7` | 《个人设置 - 通用》历史数据清理 | | `ENABLE_UPDATE_EXTRA` | 启用本地自定义更新脚本（`arcadia update`），`true` 启用，留空禁用 | 《个人设置 - 命令行》 | | `ENABLE_UPDATE_EXTRA_SYNC_FILE` | 启用远程自定义更新脚本（`arcadia update`），`true` 启用，留空禁用 | 《个人设置 - 命令行》 | | `UPDATE_EXTRA_SYNC_FILE_URL` | 远程自定义更新脚本地址（`arcadia update`） | 《个人设置 - 命令行》 | | `ENABLE_INIT_EXTRA` | 启用自定义初始化脚本（`arcadia init`），`true` 启用，留空禁用 | 《个人设置 - 命令行》 | | `ENABLE_TASK_BEFORE_EXTRA` | 启用运行代码文件运行前自定义脚本，`true` 启用，留空禁用 | 《个人设置 - 命令行》 | | `ENABLE_TASK_AFTER_EXTRA` | 启用运行代码文件运行后自定义脚本，`true` 启用，留空禁用 | 《个人设置 - 命令行》 | | `ENABLE_AUTO_DELETE_REMOTE_FILE` | 是否在运行代码文件后自动删除下载的远程文件（`arcadia run `），`true` 启用，留空禁用 | 《个人设置 - 命令行》 | | `RUN_DELAY_MAX_SECONDS` | 自定义运行代码文件延迟执行命令选项的最大随机延迟（秒）（`arcadia run --delay`），默认 `300` | 《个人设置 - 命令行》 | | `ENABLE_CUSTOM_NOTIFY` | 启用自定义推送通知模块，`true` 启用，留空禁用 | 《个人设置 - 命令行》 | | `DEFAULT_JS_RUNTIME` | 指定运行 JavaScript 脚本的默认运行时或执行器（`arcadia run`），默认 `node`，可选 `bun`、`deno` | 《个人设置 - 命令行》 | | `DEFAULT_TS_RUNTIME` | 指定运行 TypeScript 脚本的默认运行时或执行器（`arcadia run`），默认 `tsx`，可选 `bun`、`deno` 等 | 《个人设置 - 命令行》 | | `ENABLE_PYTHON_UV` | 启用 Python 脚本 uv 工具集成（`arcadia run`），`true` 启用，留空禁用 | 《个人设置 - 命令行》 | ## 用户配置（user） [#用户配置user] 不通过配置 API 暴露，由认证模块直接读写。 | 字段 | 说明 | 用途 | | ------------- | -------------------- | --------- | | `username` | 登录用户名，默认 `useradmin` | 登录认证 | | `password` | 登录密码，哈希存储 | 登录认证 | | `totpSecret` | TOTP 密钥，Base32 编码 | 双重认证（2FA） | | `totpEnabled` | `true` / `false` | 双重认证（2FA） | ## 运行时配置（runtime） [#运行时配置runtime] 系统内部使用，不通过任何配置 API 暴露。 | 字段 | 说明 | 用途 | | ---------------------- | --------------------------------- | --------------- | | `jwtSecret` | JWT 签名密钥，首次启动自动生成 | API 鉴权中间件 | | `updateCheckLastAt` | 最近一次真实检测时间（毫秒字符串） | 版本更新 - 被动检测频率控制 | | `updateCheckFailedAt` | 最近一次检测失败时间（毫秒字符串），失败后停止被动检测直到检测成功 | 版本更新 - 被动检测失败停止 | | `updatePendingCommit` | 待处理更新的目标 commit，空字符串代表无 | 版本更新 - 待更新状态 | | `updatePendingTag` | 待处理更新的版本号，空字符串代表无 | 版本更新 - 待更新状态 | | `updateCurrentTag` | 当前版本号缓存，结果含 unknown，空字符串代表从未计算过 | 版本更新 - 版本号展示 | | `updateCurrentCommit` | 当前 HEAD commit，空字符串代表从未计算过 | 版本更新 - 版本号展示 | | `updateUpgradePending` | 是否存在未完成更新任务（`true`/`false`） | 版本更新 - 更新执行互斥 | | `updateNotified` | 是否已发送过新版本提醒（`true`/`false`） | 版本更新 - 新版本提醒去重 | # 系统配置 ## 获取系统配置 [#获取系统配置] /config/system ### 响应 [#响应] ```json title="示例" { "timezone": "Asia/Shanghai", "npmRegistry": "https://registry.npmmirror.com", "pipIndexUrl": "https://mirrors.aliyun.com/pypi/simple/", "aptMirrorUrl": "http://mirrors.aliyun.com/debian", "logRetentionDays": "7", "messageRetentionDays": "7", "taskHistoryRetentionDays": "7", "cleanupCronExpression": "23 4 * * *", "cleanupCronEnabled": "true" } ``` *** ## 更新系统配置 [#更新系统配置] /config/system 支持部分字段更新，仅传入需要修改的字段即可。 ### 请求 [#请求] # 获取标签列表 /cron/bindGroup ## 请求 [#请求] 无参数 ## 响应 [#响应] ```json title="示例" [ { "bind": "", "count": 1 }, { "bind": "xxx_xxx", "count": 2 } ] ``` 目前用于系统定时任务类型过滤，使用分页接口的 `tags` 参数，具体取自 `bind` 记录值的中间字段。 # 创建 /cron ## 请求 [#请求] * CronTasksConfig ## 响应 [#响应] 参考[分页查询接口响应](/docs/api/cron/page#响应) # 数据监控 ## 获取指标数据 [#获取指标数据] /cron/dashboard/stats ### 请求 [#请求] ### 响应 [#响应] ```json title="示例" { "todaySuccessCount": 8, "todayFailureCount": 0, "yesterdaySuccessCount": 13, "yesterdayFailureCount": 1, "enabledCount": 18, "disabledCount": 23, "runningCount": 0 } ``` ## 获取任务运行趋势 [#获取任务运行趋势] /cron/dashboard/trend ### 请求 [#请求-1] ### 响应 [#响应-1] 返回对象，包含趋势数据数组和耗时排行数据 > `durationRanking.shortest[]` 的字段结构与 `durationRanking.longest[]` 完全一致。 ```json title="示例" { "trend": [ { "timestamp": 1773161661000, "taskId": 1, "taskName": "更新仓库", "taskType": "user", "duration": 21749, "success": true }, { "timestamp": 1773233647000, "taskId": 1, "taskName": "更新仓库", "taskType": "user", "duration": 7042, "success": true } ], "durationRanking": { "longest": [ { "taskId": 1, "taskName": "更新仓库", "taskType": "user", "execTimestamp": 1773161661000, "duration": 21749, "success": true } ], "shortest": [ { "taskId": 1, "taskName": "更新仓库", "taskType": "user", "execTimestamp": 1773233647000, "duration": 7042, "success": true } ] } } ``` ## 获取正在运行中的任务 [#获取正在运行中的任务] /cron/dashboard/running ### 请求 [#请求-2] ### 响应 [#响应-2] 返回数组对象 ```json title="示例" [ { "id": 1, "name": "更新仓库", "type": "user", "cron": "54 */2 * * *", "shell": "arcadia update repo" }, { "id": 2, "name": "清理日志", "type": "system", "cron": "48 5 * * *", "shell": "arcadia rmlog 7" } ... ] ``` # 删除 /cron ## 请求 [#请求] 支持批量操作 # Cron 定时任务 # 获取实时日志 /cron/liveLog ## 请求 [#请求] ## 响应 [#响应] 关于如何获取实时日志详见 [此处](/docs/api/websocket/log) # 调整排序 /cron/order ## 请求 [#请求] # 分页查询 /cron ## 请求 [#请求] ## 响应 [#响应] * CronTaskData * CronTasksConfig ```json title="示例" { "data": [ { "id": 2, "name": "系统测试任务", "type": "system", "cron": "30 */2 * * *", "shell": "arcadia run example.js", "active": 1, "config": "", "tags": "", "last_runtime": null, "last_run_use": null, "sort": 1, "create_time": "2024-01-01 00:00:00", "remark": "", "bind": "", "error_notify": 1, "is_running": false }, { "id": 1, "name": "个人测试任务", "type": "user", "cron": "0 0 * * *", "shell": "arcadia rmlog", "active": 0, "config": "", "tags": "", "last_runtime": "2024-01-01 00:00:00", "last_run_use": 1, "sort": 1, "create_time": "2024-01-01 00:00:00", "remark": "", "bind": "", "error_notify": 1, "is_running": true }, ... ], "total": 5, "page": 1, "size": 20 } ``` 默认倒序返回 # 运行 /cron/run ## 请求 [#请求] 支持批量操作 ## 完成通知 [#完成通知] 接口仅负责触发任务并立即返回。任务运行结束后，服务端会通过 WebSocket 推送 `manual: true` 的 `task:completed` 事件，详见 [定时任务状态推送](/docs/api/websocket/cron-tasks)。 # 查询运行中的任务 /cron/runningTasks ## 请求 [#请求] 无 ## 响应 [#响应] 参考[分页查询接口响应](/docs/api/cron/page#响应) # 数据关系模型 数据库对于该功能设计了三个数据表 `tasks`、`taskCore` 和 `tasksExecutionStats`。`taskCore` 表专用于关联定时任务工作引擎。 `tasksExecutionStats` 表用于记录定时任务的执行统计数据。 ```prisma model taskCore { id String @id cron String callback String } model tasks { id Int @id @default(autoincrement()) name String cron String type String shell String @default("") active Int @default(1) last_runtime DateTime? last_run_use Int? tags String @default("") sort Int @default(99999) create_time DateTime @default(now()) config String @default("") remark String @default("") bind String @default("") error_notify Int @default(1) } model tasksExecutionStats { id Int @id @default(autoincrement()) task_id Int task_name String task_type String exec_timestamp BigInt duration Int success Int create_time DateTime @default(now()) @@index([task_id, exec_timestamp]) @@index([exec_timestamp]) @@index([task_type, exec_timestamp]) } ``` ## 工作原理 [#工作原理] 定时任务的生命周期由 Cron 引擎驱动，整体流程如下： ### 流程说明 [#流程说明] | 阶段 | 说明 | | ----------------------- | ---------------------------- | | Cron 引擎触发 | node-cron 按 cron 表达式触发定时回调 | | runCronTask | 任务执行入口，负责并发检查和状态管理 | | runTaskModel | 执行具体的任务模型（Shell 命令） | | emitTaskStarted | 通过 WebSocket 推送任务开始事件 | | execShell | 执行 Shell 脚本，捕获 stdout/stderr | | onExit 回调 | Shell 进程退出后触发清理和持久化 | | cleanupRunningTaskState | 清理运行中任务的状态缓存 | | emitTaskCompleted | 通过 WebSocket 推送任务完成事件 | | persistTaskExecution | 持久化任务执行记录到数据库 | | notifyTaskFailure | 任务失败时发送通知（需开启 error\_notify） | # 终止 /cron/terminate ## 请求 [#请求] 支持批量操作 # 修改 /cron ## 请求 [#请求] * CronTasksConfig 支持批量操作（改成数组） ## 响应 [#响应] 返回布尔值，如果是批量创建只要有一个失败就返回 `false` # 名称检查 /daemon/check ## 请求 [#请求] ## 响应 [#响应] 检查名称是否与已有守护任务或 PM2 系统进程（如 arcadia\_server、tgbot）冲突。 # 创建与更新 /daemon/save ## 请求 [#请求] 不传 `id` 时创建新任务，传 `id` 时更新已有任务。 创建时会自动检查名称是否与已有守护任务或 PM2 系统进程冲突。 # 删除 /daemon ## 请求 [#请求] 删除时会同时停止并移除对应的 PM2 进程，清理相关的定时重启计划。 # Daemon 守护任务 # 获取列表 /daemon ## 请求 [#请求] 无参数 ## 响应 [#响应] 返回所有守护任务的数组，每个元素包含数据库字段以及 PM2 运行时状态信息。 # 日志查看 /daemon/log ## 请求 [#请求] ## 响应 [#响应] 日志路径由任务的 `log_dir` 和 `log_name` 字段拼接而成。支持通过 `startLine` 参数实现增量加载，避免大日志文件的全量传输。 # 数据关系模型 数据表用于存储守护任务的配置信息。守护任务通过 PM2 进程管理器运行，运行时状态从 PM2 实时获取。 ```prisma model daemonTask { id Int @id @default(autoincrement()) name String @unique file_path String description String @default("") boot_start Int @default(1) max_restarts Int @default(-1) restart_delay Int @default(0) restart_cron String @default("") autorestart Int @default(1) max_memory_restart Int @default(0) stop_exit_codes Int @default(-1) exp_backoff_restart_delay Int @default(0) envs String @default("[]") options String @default("[]") log_dir String @default("") log_name String @default("") log_max_lines Int @default(0) active Int @default(1) created_at DateTime @default(now()) updated_at DateTime @updatedAt } ``` ### 字段说明 [#字段说明] | 字段 | 说明 | | --------------------------- | -------------------------------------------------------- | | `name` | 任务名称，全局唯一，同时作为 PM2 进程名称 | | `file_path` | 要执行的脚本文件路径 | | `description` | 任务描述 | | `boot_start` | 系统启动时是否自动拉起，1 启用，0 禁用 | | `max_restarts` | 最大重启次数，-1 表示无限制 | | `restart_delay` | 崩溃重启延迟，单位毫秒 | | `restart_cron` | 定期重启的 cron 表达式，为空则不启用 | | `autorestart` | 崩溃时是否自动重启，1 启用，0 禁用 | | `max_memory_restart` | 内存超限重启阈值（MB），0 表示不启用 | | `stop_exit_codes` | 遇到该退出码时停止自动重启，-1 表示不启用 | | `exp_backoff_restart_delay` | 指数退避重启初始延迟（毫秒），0 表示不启用 | | `envs` | 附加环境变量，JSON 数组格式 `{ key: string, value: string }[]` | | `options` | 传递给脚本的命令行选项，JSON 数组格式 `{ key: string, value: string }[]` | | `log_dir` | 日志目录路径，为空使用项目默认目录 | | `log_name` | 日志文件名（不含扩展名） | | `log_max_lines` | 日志最大保留行数，0 表示不限制 | | `active` | 是否启用，1 启用，0 禁用 | # 日志裁剪 /daemon/log/trim ## 请求 [#请求] 手动裁剪指定守护任务的日志文件，按照任务配置的 `log_max_lines` 保留最新的日志行数。如果任务未配置 `log_name` 或 `log_max_lines` 为 0，接口将返回错误。 # 执行操作 /daemon/action ## 请求 [#请求] ### action 说明 [#action-说明] | 值 | 说明 | | --------- | ---------------------------------------------------------------- | | `start` | 启动守护任务。通过 `arcadia rund` 重新拉起进程，启动前会自动裁剪日志（如配置了 `log_max_lines`） | | `stop` | 停止守护任务对应的 PM2 进程 | | `restart` | 重启守护任务。先删除旧 PM2 进程，再以最新数据库配置重新启动，确保配置变更立即生效 | | `flush` | 清空 PM2 为该任务缓存的日志内容 | # 新增 /dependency ## 请求 [#请求] ## 响应 [#响应] 单个字符串时返回新创建的依赖记录，字段同 [数据关系模型](./schema)；字符串数组时返回批量创建结果： 单个与批量统一走同一套逐项校验：包名非空、非平台保留依赖、不与已有记录重复， 任一不合法则整体报错；批次内重复项自动去重。批量新增仅创建记录，不会自动触发安装。 # 删除 /dependency ## 请求 [#请求] 状态为安装中（1）或卸载中（4）的依赖不允许删除。\ 删除记录不会自动卸载对应的包，包体仍会保留在系统中，如需卸载请先执行卸载操作。 # 查看错误日志 /dependency/error 查询某条依赖记录最近一次失败时的命令输出。安装成功后该字段会自动清空。 ## 请求 [#请求] Query 参数： ## 响应 [#响应] # Dependency 依赖管理 # 分页查询 /dependency ## 请求 [#请求] Query 参数： ## 响应 [#响应] `DepItem` 结构同 [数据关系模型](./schema) 中的字段。 # 操作 /dependency/operate 对依赖执行安装、卸载或状态同步操作。安装和卸载任务通过串行队列执行，不会并发。\ 每个任务完成后通过 WebSocket `depOperateResult` 事件实时推送结果。 ## 请求 [#请求] ## 响应 [#响应] ### install / uninstall [#install--uninstall] ### sync [#sync] # 数据关系模型 数据库用于存储依赖记录的元数据。依赖的安装、卸载和版本检测通过 `shell/utils/dep.sh` 脚本完成，脚本执行结果回写到数据库。 ```prisma model dependencyManage { id Int @id @default(autoincrement()) name String ecosystem String installed_ver String @default("") status Int @default(0) last_error String @default("") remark String @default("") create_time DateTime @default(now()) update_time DateTime @default(now()) @updatedAt @@unique([name, ecosystem]) @@index([ecosystem, status]) @@index([ecosystem]) } ``` ### 字段说明 [#字段说明] | 字段 | 说明 | | --------------- | -------------------------------------------------- | | `name` | 包名，可携带版本表达式，如 `axios@1.7.0`、`requests>=2.0`、`curl` | | `ecosystem` | 包管理生态，固定为 `npm`、`pnpm`、`pip`、`apt` 之一 | | `installed_ver` | 安装成功后回写的实际版本号；空字符串表示尚未安装 | | `status` | 状态码，见下表 | | `last_error` | 最近一次失败时的命令输出（截取前 8000 字节）；安装成功时自动清空 | | `remark` | 用户备注 | | `create_time` | 记录创建时间 | | `update_time` | 记录最后更新时间 | ### 状态码 [#状态码] | 值 | 含义 | | --- | --- | | `0` | 未安装 | | `1` | 安装中 | | `2` | 已安装 | | `3` | 失败 | | `4` | 卸载中 | # 更改状态 ## 变量项 [#变量项] /env/changeStatusItem ### 请求 [#请求] ## 变量组 [#变量组] /env/changeStatus ### 请求 [#请求-1] # 创建 支持批量操作 ## 变量项 [#变量项] /env/createItem ### 请求 [#请求] ## 变量组 [#变量组] /env/create ### 请求 [#请求-1] # 删除 ## 变量项 [#变量项] /env/deleteItem ### 请求 [#请求] ## 变量组 [#变量组] /env/delete ### 请求 [#请求-1] # Env 环境变量 # 调整排序 ## 变量项 [#变量项] /env/orderItem ### 请求 [#请求] ## 变量组 [#变量组] /env/order ### 请求 [#请求-1] # 分页查询 ## 变量项 [#变量项] /env/pageItem ### 请求 [#请求] ### 响应 [#响应] * EnvsData ```json title="示例" { "data": [ { "id": 1, "group_id": 0, "type": "TEST1", "tag_list": "[{\"label\":\"test\"}]", "description": "", "remark": "", "update_time": "2024-05-01 00:00:00", "value": "测试1", "sort": 0, "enable": 1 }, { "id": 2, "group_id": 0, "type": "TEST2", "tag_list": "", "description": "", "remark": "", "update_time": "2024-05-01 00:00:01", "value": "测试2", "sort": 0, "enable": 0 }, ... ], "total": 5, "page": 1, "size": 20 } ``` ## 变量组 [#变量组] /env/page ### 请求 [#请求-1] ### 响应 [#响应-1] 数据项（主要为数据库 envsGroup 表记录） ```json title="示例" { "data": [ { "id": 1, "type": "TEST1", "description": "", "update_time": "2024-05-01 00:00:00", "tag_list": "", "separator": "", "sort": 1, "enable": 1, "envs": 0 }, { "id": 2, "type": "TEST2", "description": "@", "update_time": "2024-05-01 00:00:01", "tag_list": "", "separator": "", "sort": 0, "enable": 1, "envs": 3 }, ... ], "total": 3, "page": 1, "size": 20 } ``` 默认倒序返回 # 更新插入 ## 变量项 [#变量项] /env/saveItem ### 请求 [#请求] ## 变量组 [#变量组] /env/save ### 请求 [#请求-1] # 数据关系模型 此部分与 API 紧密相连，如果你无法理解项目应用程序设计那么请谨慎操作，建议先了解前端实现或直接使用 OpenAPI 数据库对于该功能设计了两个数据表 `envs` `envsGroup`，分别代表变量项和变量组 ```prisma model envs { id Int @id @default(autoincrement()) group_id Int type String tag_list String @default("") description String @default("") remark String @default("") value String @default("") sort Int @default(0) enable Int @default(1) envs_group envs_group? @relation(fields: [group_id], references: [id]) @@index([type]) } model envsGroup { id Int @id @default(autoincrement()) type String description String @default("") tag_list String @default("") separator String @default("") sort Int @default(0) enable Int @default(1) envs envs[] @@index([type]) } ``` * `envs` 表 用于存储所有普通变量和复合变量的成员值，复合变量的成员值不使用 `type`、`tag_list`、`description` 字段\ 其中 `group_id` 字段用于关联 envsGroup 表的 `id` 字段，为 `0` 时表示记录项是一个普通变量 * envsGroup 表 用于存储组变量（复合变量） `envs` 表存储所有普通变量和复合变量(组)成员的值，其中 `group_id` 为 `0` 时视为普通变量。envsGroup 表存储所有复合变量(组)。 ## 具体字段说明 [#具体字段说明] ### 通用字段 [#通用字段] ### `envs` 表专用字段 [#envs-表专用字段] ### envsGroup 表专用字段 [#envsgroup-表专用字段] # 获取所有标签 ## 变量项 [#变量项] /env/tagsItem ### 请求 [#请求] ### 响应 [#响应] 返回数组对象 ## 变量组 [#变量组] /env/tags ### 请求 [#请求-1] 无 ### 响应 [#响应-1] 返回数组对象 # 执行 Shell 命令 /exec/cmd ## 请求 [#请求] ## 响应 [#响应] 返回事件 ID 字符串，关于如何获取日志详见 [获取实时日志](/docs/api/websocket/log)。 # 运行代码文件 ## 运行 [#运行] /exec/file ### 请求 [#请求] ### 响应 [#响应] 返回事件 ID 字符串，关于如何获取日志详见 [获取实时日志](/docs/api/websocket/log)。 ## 获取运行命令 [#获取运行命令] /exec/file/command 获取运行指定代码文件时实际执行的 shell 命令字符串（不执行，仅返回命令），可用于在终端中手动运行。支持传入命令选项和环境变量配置。 ### 请求 [#请求-1] ### 响应 [#响应-1] 返回完整的 shell 命令字符串。 ## 调试运行 [#调试运行] /exec/file/debug 会创建临时文件并在运行完毕后自动清理，不修改原始代码文件内容。 ### 请求 [#请求-2] ### 响应 [#响应-2] 返回事件 ID 字符串，关于如何获取日志详见 [获取实时日志](/docs/api/websocket/log)。 ## 终止运行 [#终止运行] /exec/file/stop ### 请求 [#请求-3] ### 响应 [#响应-3] 返回事件 ID 字符串，关于如何获取日志详见 [获取实时日志](/docs/api/websocket/log)。 # Exec 命令执行 # 获取运行状态 /exec/status ## 请求 [#请求] ## 响应 [#响应] # 查询属性 /file/info ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" { "type": "file", "name": "example", "parent_path": "/arcadia/log", "mode": "644", "size": 2048, "display_size": "2.00 KB", "modified_time": "2024-01-01 00:00:00", "accessed_time": "2024-01-01 00:00:00", "created_time": "2024-01-01 00:00:00", "changed_time": "2024-01-01 00:00:00" } ``` # 创建 /file/create ## 请求 [#请求] # 删除 /file/delete ## 请求 [#请求] 支持批量 # 下载 /file/download ## 请求 [#请求] 下载目录时会压缩成 `zip` 文件 # 获取文件内容 /file/content ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" function template() {\n console.log(\"Hello World\");\n} ``` # File 文件系统 # 获取文件列表 /file/list ## 请求 [#请求] ## 响应 [#响应] * FileListChildren ```json title="示例" { "path": "/arcadia", "title": "arcadia", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00", "children": [ { "path": "/arcadia/config", "name": "config", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" }, { "path": "/arcadia/log", "name": "log", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" }, { "path": "/arcadia/raw", "name": "raw", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" }, { "path": "/arcadia/repo", "name": "repo", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" }, { "path": "/arcadia/scripts", "name": "scripts", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" }, { "path": "/arcadia/src", "name": "src", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" } ] } ``` # 移动 /file/move ## 请求 [#请求] # 重命名 /file/rename ## 请求 [#请求] # 保存文件内容 /file/content ## 请求 [#请求] # 全局文件搜索 ## 代码目录搜索 [#代码目录搜索] /file/search ### 请求 [#请求] ### 响应 [#响应] 与 [获取文件树](/docs/api/file/tree) 响应结构相同，返回匹配关键字的文件树数组。 含有 `children` 属性的对象为目录，应使用 `title` 字段获取目录名称 ```json title="示例" [ { "path": "/arcadia/repo", "title": "repo", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00", "children": [ { "path": "/arcadia/repo/my-project/index.js", "name": "index.js", "type": "file", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" } ] } ] ``` ## 日志目录搜索 [#日志目录搜索] /file/search/log 仅返回位于日志目录内的目录和 `.log` 后缀文件。 ### 请求 [#请求-1] ### 响应 [#响应-1] 与[代码目录搜索响应](#代码目录搜索)相同 # 获取文件树 该接口已弃用 ## 通用 [#通用] /file/tree ### 请求 [#请求] ### 响应 [#响应] 含有 `children` 属性的对象为目录，应使用 `title` 字段获取目录名称 ```json title="示例" [ { "path": "/arcadia", "title": "arcadia", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00", "children": [ { "path": "/arcadia/script", "title": "script", "type": "folder", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00", "children": [ { "path": "/arcadia/script/example.js", "name": "example.js", "type": "file", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" }, { "path": "/arcadia/script/template.sh", "name": "template.sh", "type": "file", "updated_at": "2024-01-01 00:00:00", "created_at": "2024-01-01 00:00:00" }, ... ] }, ... ] } ] ``` 不包含 `log` 目录和一些不适合展示的文件目录 ## 获取指定类型的文件树 [#获取指定类型的文件树] /file/tree/:type ### 请求 [#请求-1] * FileTreeType | 名称 | 含义 | | :----------: | :-------------------: | | `all` | 全部 | | `arcadia` | `/arcadia` | | `src` | `/arcadia/src` | | `config` | `/arcadia/config` | | `sample` | `/arcadia/src/sample` | | `scripts` | `/arcadia/scripts` | | `shell` | `/arcadia/src/shell` | | `log` | `/arcadia/log` | | `repo` | `/arcadia/repo` | | `raw` | `/arcadia/raw` | | `config_bak` | `/arcadia/config/bak` | 类型 `arcadia` 等价于 `all`，且均不包含 `log` 目录和一些不适合展示的文件目录\ 使用 `arcadia` 或 `all` 时与 [通用](#通用) 接口响应相同，即获取完整文件树 ### 响应 [#响应-1] 参考上方[接口响应](#通用) # 上传文件 /file/upload 接口特殊，使用 query 即 `URLParams` 传参，暂不支持上传目录 # 历史数据清理 /api/log/cleanup 清理各类业务数据与日志 ## 请求 [#请求] ## 响应 [#响应] * CleanupLogResult ```json title="示例" { "log": { "serverLog": 120, "loginLog": 45 }, "message": { "count": 30 }, "taskHistory": { "count": 15 } } ``` 各类型的保留天数分别由《个人设置 - 通用》中的 “数据与日志清理” 配置控制，默认均为 7 天。\ 系统日志 `log` 类型总共包含系统操作日志、登录日志、开放接口日志、代码文件运行日志。 # 清空指定类型日志 /api/log/clear 清空指定类型的系统日志全部记录。 ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" { "count": 128 } ``` 该操作会删除对应类型的全部日志，且不可恢复。 # Log 系统日志 # 获取登录日志 /log/login ## 请求 [#请求] ## 响应 [#响应] * SystemLogLoginData ```json title="示例" { "data": [ { "id": 2, "time": "2026-01-01 00:00:00", "address": "局域网", "ip": "192.168.1.1", "result": 1 }, { "id": 1, "time": "2026-01-01 00:00:00", "address": "局域网", "ip": "192.168.1.1", "result": 0 } ... ], "total": 5, "page": 1, "size": 20 } ``` 默认倒序返回 # 获取开放接口日志 /log/openapi ## 请求 [#请求] ## 响应 [#响应] * OpenApiLogItem ```json title="示例" { "data": [ { "id": 1, "time": "2025-01-01T12:00:00.000Z", "method": "GET", "path": "/file/list", "ip": "1.2.3.4", "address": "中国 广东 深圳", "browser": "Chrome 128", "os": "Windows 11", "device": "Desktop" }, { "id": 2, "time": "2025-01-01T11:55:00.000Z", "method": "POST", "path": "/script/run", "ip": "1.2.3.4", "address": "中国 广东 深圳", "browser": "Chrome 128", "os": "Windows 11", "device": "Desktop" } ], "total": 2, "page": 1, "size": 20 } ``` 默认倒序返回 # 获取操作日志 /log/server ## 请求 [#请求] ## 响应 [#响应] * SystemLogServerData ```json title="示例" { "data": [ { "id": 2, "time": "2026-01-01 00:00:00", "content": "用户已建立 WebSocket 连接", "type": "info" }, { "id": 1, "time": "2026-01-01 00:00:00", "content": "用户 admin 已登录，登录地址：192.168.1.1 局域网", "type": "info" } ... ], "total": 5, "page": 1, "size": 20 } ``` 默认倒序返回 # 删除 ## 删除消息 [#删除消息] /message ## 请求 [#请求] ## 清空所有消息 [#清空所有消息] /message/all ## 请求 [#请求-1] ## 响应 [#响应] # 获取详情 /message ## 请求 [#请求] ## 响应 [#响应] # 消息中心 # 分页查询 /message/list ## 请求 [#请求] ## 响应 [#响应] * MessageData # 数据关系模型 消息中心的数据模型用于存储系统内各类通知消息，支持分类过滤、去重合并和已读状态管理。 ```prisma // 消息中心通知 model message { id Int @id @default(autoincrement()) category String @default("system") // 系统类型 user,system,cron 等 type String @default("info") // info, warn, error, success title String content String status Int @default(0) // 0:未读 1:已读 create_time DateTime @default(now()) @@index([category]) @@index([status, create_time]) @@index([create_time]) } ``` ### 字段说明 [#字段说明] | 字段 | 说明 | | ------------ | ------------------------------------------------------------- | | category | 消息分类，默认 `system`。常见值：`user`（用户消息）、`system`（系统消息）、`cron`（定时任务） | | type | 消息类型，默认 `info`。可选值：`info`、`warn`、`error`、`success` | | title | 消息标题，必填，最大 200 字符 | | content | 消息内容，必填，最大 20000 字符 | | status | 已读状态。`0` 未读，`1` 已读 | | create\_time | 创建时间 | # 更新已读状态 支持批量操作 /message/status ## 请求 [#请求] ## 更新全部消息 [#更新全部消息] /message/status/all ### 请求 [#请求-1] # 获取未读消息计数 /message/unread/count ## 请求 [#请求] 无请求参数。 ## 响应 [#响应] # 创建 /token ## 请求 [#请求] ## 响应 [#响应] 参考[获取列表响应](/docs/api/token/list#响应) # 删除 /token ## 请求 [#请求] # Token 令牌管理 通过 Token 令牌界面创建和管理 OpenAPI 访问凭证。每个令牌可独立分配一组细粒度权限，仅允许访问授权范围内的接口。 关于权限系统的详细说明，参阅《[**权限说明**](/docs/api/token/permission)》。 # 获取列表 /token ## 请求 [#请求] 无参数 ## 响应 [#响应] ```json title="示例" [ { "id": 1, "name": "新建令牌", "value": "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456", "expire_time": null, "enable": 1, "create_time": "2024-01-01 00:00:00", "update_time": "2024-01-01 00:00:00", }, ... ] ``` # 权限说明 ## 概述 [#概述] OpenAPI 令牌采用细粒度的 `资源:操作` 权限模型。每个令牌在创建时可以指定一组权限键，接口请求时会校验令牌是否拥有该路由所需的权限。 权限以逗号分隔的字符串存储，例如 `cron:query,env:query,env:manage`。 不携带任何权限字段或权限字段为空字符串时，令牌将自动使用**默认安全权限集**，不会继承全部权限。 ## 默认权限集 [#默认权限集] 新建令牌时若不指定 `permissions` 字段，将使用以下默认权限集（仅包含只读与低风险操作）： | 权限键 | 说明 | | --------------- | --------- | | `cron:query` | 查询定时任务 | | `env:query` | 查询环境变量 | | `env:manage` | 管理环境变量 | | `file:list` | 列出文件目录 | | `message:push` | 推送消息到消息中心 | | `message:query` | 查询消息 | ## 权限键一览 [#权限键一览] 定时任务 (cron) 环境变量 (env) 文件系统 (file) 命令执行 (exec) 消息中心 (message) | 权限键 | 说明 | 默认启用 | 危险 | | ------------- | ----------------- | :--: | :-: | | `cron:query` | 查询、分页列表、获取标签和运行状态 | ✅ | — | | `cron:manage` | 创建、修改、删除定时任务及调整排序 | — | ⚠️ | | `cron:run` | 手动触发或终止定时任务的执行 | — | ⚠️ | | 接口路径 | 方法 | 所需权限 | | ----------------------- | ---- | ------------- | | `/cron/v1/page` | GET | `cron:query` | | `/cron/v1/query` | GET | `cron:query` | | `/cron/v1/runningTasks` | GET | `cron:query` | | `/cron/v1/tagsList` | GET | `cron:query` | | `/cron/v1/create` | POST | `cron:manage` | | `/cron/v1/update` | POST | `cron:manage` | | `/cron/v1/delete` | POST | `cron:manage` | | `/cron/v1/order` | POST | `cron:manage` | | `/cron/v1/run` | POST | `cron:run` | | `/cron/v1/terminate` | POST | `cron:run` | | 权限键 | 说明 | 默认启用 | 危险 | | ------------ | ------------------ | :--: | :-: | | `env:query` | 查询、分页列表及获取环境变量详情 | ✅ | — | | `env:manage` | 创建、修改、删除、排序及批量导入导出 | ✅ | — | | 接口路径 | 方法 | 所需权限 | | ---------------------- | ---- | ------------ | | `/env/v1/page` | GET | `env:query` | | `/env/v1/query` | GET | `env:query` | | `/env/v1/queryMember` | GET | `env:query` | | `/env/v1/queryById` | GET | `env:query` | | `/env/v1/tags` | GET | `env:query` | | `/env/v1/create` | POST | `env:manage` | | `/env/v1/update` | POST | `env:manage` | | `/env/v1/delete` | POST | `env:manage` | | `/env/v1/order` | POST | `env:manage` | | `/env/v1/changeStatus` | POST | `env:manage` | | 权限键 | 说明 | 默认启用 | 危险 | | ------------ | ----------------- | :--: | :-: | | `file:list` | 获取目录列表、文件树和文件属性 | ✅ | — | | `file:read` | 读取任意文件内容及下载文件 | — | ⚠️ | | `file:write` | 创建、修改、重命名、移动、删除文件 | — | ⚠️ | | 接口路径 | 方法 | 所需权限 | | ------------------- | ---- | ------------ | | `/file/v1/list` | GET | `file:list` | | `/file/v1/info` | GET | `file:list` | | `/file/v1/content` | GET | `file:read` | | `/file/v1/download` | GET | `file:read` | | `/file/v1/content` | POST | `file:write` | | `/file/v1/rename` | POST | `file:write` | | `/file/v1/move` | POST | `file:write` | | `/file/v1/create` | POST | `file:write` | | `/file/v1/delete` | POST | `file:write` | | `/file/v1/upload` | POST | `file:write` | | 权限键 | 说明 | 默认启用 | 危险 | | ------------- | ---------------- | :--: | :-: | | `exec:cmd` | 执行 Shell 命令 | — | ⚠️ | | `exec:file` | 运行指定路径的代码代码文件 | — | ⚠️ | | `exec:status` | 查询命令或代码文件的当前运行状态 | — | ⚠️ | | 接口路径 | 方法 | 所需权限 | | ---------------------- | ---- | ------------- | | `/exec/v1/cmd` | POST | `exec:cmd` | | `/exec/v1/cmd/stream` | POST | `exec:cmd` | | `/exec/v1/file` | POST | `exec:file` | | `/exec/v1/file/stream` | POST | `exec:file` | | `/exec/v1/file/stop` | POST | `exec:file` | | `/exec/v1/status` | GET | `exec:status` | | 权限键 | 说明 | 默认启用 | 危险 | | ---------------- | ---------------- | :--: | :-: | | `message:push` | 向消息中心推送用户消息 | ✅ | — | | `message:query` | 分页查询、获取未读计数和消息详情 | ✅ | — | | `message:manage` | 标记消息已读和删除消息 | — | — | | 接口路径 | 方法 | 所需权限 | | ------------------------- | ---- | ---------------- | | `/message/v1/create` | POST | `message:push` | | `/message/v1/page` | GET | `message:query` | | `/message/v1/unreadCount` | GET | `message:query` | | `/message/v1/detail` | GET | `message:query` | | `/message/v1/readStatus` | POST | `message:manage` | | `/message/v1/readAll` | POST | `message:manage` | | `/message/v1/delete` | POST | `message:manage` | **危险权限**（⚠️）在创建令牌时默认禁用，需显式传入权限键方可启用。请仅在必要时授予，并严格控制令牌的分发范围。 # 更新 /token ## 请求 [#请求] ## 响应 [#响应] 参考[获取列表响应](/docs/api/token/list#响应) # 一键更新 /api/update/apply 触发更新执行。直接使用最近一次检测到的可更新目标启动后台更新，启动后立即返回，不阻塞更新任务；更新结果通过 Socket 广播 `update:refresh` 通知前端。 ## 请求 [#请求] 无请求体。 ## 响应 [#响应] 无响应内容，`result` 固定为 `true`，表示已转入后台执行。 # 检查更新 /api/update/check 执行真实更新检测（git fetch + Releases API），返回检测状态、当前版本与可更新目标。并发请求复用同一次检测；更新任务执行中拒绝检测；主动检测不推送消息中心通知。 ## 请求 [#请求] 无请求参数。 ## 响应 [#响应] # 版本更新 版本更新以 Git commit 判定为准，数字版本号只作展示 # 版本快照 /api/update 获取当前版本与更新状态快照，只读本地缓存与 git（版本号从未计算过时现算一次），不发起网络请求。 ## 请求 [#请求] 无请求参数。 ## 响应 [#响应] # 登录认证 /user/auth ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" { "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", "newPwd": "" } ``` Token 有效时长：72小时 `newPwd` 仅在系统强制更改用户密码后才返回，根据策略目前仅判断用户密码是否为初始密码，如果是则返回一个由随机字符组成的新密码，否则返回空字符串，密码变更后控制面板会有通知提醒。\ 基础参数验证通过后就会响应 `success` 成功，如果启用了双重认证则不会返回 `token`，需要继续调用下方的接口。 ### 2FA 双重认证 [#2fa-双重认证] /user/auth/twoFactor #### 请求 [#请求-1] #### 响应 [#响应-1] # 更改认证信息 /user/changePwd ## 请求 [#请求] # User 用户 # 获取用户信息 /user/info ## 请求 [#请求] 无参数 ## 响应 [#响应] * LastLoginInfo ```json title="示例" { "username": "admin", "lastLoginInfo": { "loginIp": "127.0.0.1", "loginAddress": "局域网", "loginTime": "2024-01-01 00:00:00" } } ``` # 登出所有设备 注销所有令牌 /user/revokeAllTokens ## 请求 [#请求] 无参数 # 配置双重认证 (2FA) 基于 TOTP (Time-Based One-Time Passwords) [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238) 标准 ## 获取启用状态 [#获取启用状态] /user/twoFactorAuth/status ### 请求 [#请求] 无参数 ## 初始化配置 [#初始化配置] /user/twoFactorAuth/setup ### 请求 [#请求-1] ### 响应 [#响应] ```json title="示例" { "secret": "JBSWY3DPEHPK3PXP", "otpauthUrl": "otpauth://totp/Arcadia:useradmin?secret=JBSWY3DPEHPK3PXP&issuer=Arcadia&algorithm=SHA1&digits=6&period=30", "issuer": "Arcadia", "message": "请使用 Google Authenticator 或 Microsoft Authenticator 扫描二维码" } ``` ## 启用 [#启用] /user/twoFactorAuth/enable ### 请求 [#请求-2] 验证通过才会启用 ## 关闭 [#关闭] /user/twoFactorAuth/disable ### 请求 [#请求-3] 无参数 # 定时任务状态推送 当定时任务开始或结束时，服务端会主动向所有已连接的客户端广播任务状态变更事件。 ## 执行开始 [#执行开始] 定时任务开始执行时触发，在任务运行前推送。 接口路径：`/api/ws`\ 事件名称：`task:started`\ 方向：服务端 → 客户端 ## 执行结束 [#执行结束] 定时任务执行完毕后触发，无论成功或失败均会推送。 接口路径：`/api/ws`\ 事件名称：`task:completed`\ 方向：服务端 → 客户端 # 守护任务实时日志 守护任务实时日志的订阅与推送，已合并到默认命名空间。 接口路径：`/api/ws`\ 事件名称：`daemon:log:subscribe` / `daemon:log:unsubscribe` / `daemon:log:data` ## 订阅 [#订阅] 事件名称：`daemon:log:subscribe` 订阅成功后，服务端持续推送该任务的新增日志。 ```ts socket.emit('daemon:log:subscribe', { id: 1 }) socket.on('daemon:log:data', (content: string) => { // 追加展示 }) ``` ## 取消订阅 [#取消订阅] 事件名称：`daemon:log:unsubscribe`，无载荷。服务端按当前连接清理订阅；连接断开时也会自动清理。 ```ts socket.emit('daemon:log:unsubscribe') ``` ## 日志数据 [#日志数据] 事件名称：`daemon:log:data`，载荷为新增日志内容字符串。 # 依赖管理操作结果 在操作依赖（安装、卸载、同步）后，返回依赖项数据用于实时更新 接口路径：`/api/ws`\ 事件名称：`dep:operate`\ 方向：服务端 → 客户端 根据业务场景返回部分字段，不返回完整记录数据。 # WebSocket ## 连接说明 [#连接说明] * 服务地址：`/api/ws`（与 HTTP 同源部署时使用相对路径，跨域部署时使用完整地址）； * 命名空间：默认 `/` 与 `/terminal`； * 认证：连接时在 `Authorization` 头携带 `Bearer `，与 HTTP API 使用同一 JWT； * 事件命名：统一为 `领域:动作`，全部小写，如 `run:log`、`task:started`、`daemon:log:data`。 ## 事件分类 [#事件分类] * 全局事件（默认命名空间）：实时日志、任务状态、依赖操作、消息、版本更新； * 终端（`/terminal` 命名空间）：终端会话的输入输出与生命周期； * 守护日志（默认命名空间）：守护任务实时日志的订阅与推送。 ## 连接示例 [#连接示例] ```ts import { io } from 'socket.io-client' // 默认命名空间 const socket = io({ path: '/api/ws', extraHeaders: { Authorization: `Bearer ${token}` } }) // 终端命名空间 const terminal = io('/terminal', { path: '/api/ws', extraHeaders: { Authorization: `Bearer ${token}` } }) ``` # 代码运行实时日志 代码运行（执行命令、运行文件、手动运行任务）期间实时推送日志分片，直到运行结束。 同一 `runId` 的分片按产生顺序推送，`over: true` 表示该次运行结束，之后不再推送。 接口路径：`/api/ws`\ 事件名称：`run:log`\ 方向：服务端 → 客户端 ## 载荷 [#载荷] 外层为统一响应信封： `result` 字段： # 新消息通知 系统产生新消息时推送，前端用于刷新未读消息数量与消息列表。 接口路径：`/api/ws`\ 事件名称：`message:new`\ 方向：服务端 → 客户端 # 终端 终端会话使用独立的 `/terminal` 命名空间，一个连接同时只允许一个终端会话。 接口路径：`/api/ws`\ 命名空间：`/terminal`\ 认证：与主连接一致，`Authorization` 头携带 `Bearer ` ## 客户端 → 服务端 [#客户端--服务端] ### 创建会话 [#创建会话] 事件名称：`terminal:spawn` ```ts socket.emit('terminal:spawn', { cols: 80, rows: 24, cwd: '/arcadia' }) socket.on('terminal:output', (data: string) => { // 追加到终端 }) ``` ### 输入 [#输入] 事件名称：`terminal:input`，载荷为字符串。 ### 调整尺寸 [#调整尺寸] 事件名称：`terminal:resize` ## 服务端 → 客户端 [#服务端--客户端] ### 就绪 [#就绪] 事件名称：`terminal:ready`，无载荷。会话创建成功后可开始输入。 ### 输出 [#输出] 事件名称：`terminal:output`，载荷为字符串。 ### 退出 [#退出] 事件名称：`terminal:exit`，载荷为进程退出码（number）。 ### 错误 [#错误] 事件名称：`terminal:error`，载荷为错误信息字符串。 ## 注意事项 [#注意事项] * 每个连接只允许一个会话，重复 `terminal:spawn` 会返回 `terminal:error`； * 连接断开时服务端会自动结束并清理当前会话。 # 版本更新状态刷新 版本检测或更新流程中状态发生变化时推送，前端收到后重新拉取版本快照。 接口路径：`/api/ws`\ 事件名称：`update:refresh`\ 方向：服务端 → 客户端 无载荷（空对象）。 # 用户环境变量 该命令当前仅支持管理用户配置文件（非数据库）中用 `export` 关键字声明的全局变量 ```sh title="$ arcadia envm" ❖ Arcadia CLI - 用户环境变量管理 使用方法： arcadia envm [...] 子命令： add [ ] 添加变量 edit [ ] 修改变量 del [] 删除变量 search [] 查询变量 enable 启用变量 disable 禁用变量 命令帮助： [xxx] 可选的快捷子命令 环境变量名称 环境变量值 环境变量备注 搜索关键字 ``` 命令默认通过 `交互` 管理全局环境变量，支持快捷命令一键执行对应操作 在使用快捷命令时，如果变量的**值**或**备注内容**含有`空格`或其它`特殊符号`，应使用引号将其扩起来以表示整体 ## 添加变量 [#添加变量] ```bash arcadia envm add ``` ```bash title="快捷命令" arcadia envm add <变量名称> <变量的值> <备注> ``` 可以省略 `<备注>` 参数，那么目标变量的备注内容将自动设置为登记时间以用于备忘记录 ## 修改变量 [#修改变量] ```bash arcadia envm edit ``` ```bash title="快捷命令" arcadia envm edit <变量名称> <变量新的值> <备注> ``` 可以省略 `<备注>` 参数即不修改备注内容，如果检测到未添加目标变量则将自动添加 ## 删除变量 [#删除变量] ```bash arcadia envm del ``` ```bash title="快捷命令" arcadia envm del <变量名称> ``` ## 查询变量 [#查询变量] ```bash arcadia envm search ``` ```bash title="快捷命令" arcadia envm search <查询关键词> ``` ## 启用/禁用变量 [#启用禁用变量] 此命令的常规交互使用方法集成在修改变量功能中，与其它命令的快捷命令不同 ```bash arcadia envm enable/disable <变量名称> ``` # 添加代码文件 ```sh title="$ arcadia raw" ❖ Arcadia CLI - 导入代码文件配置 使用方法： arcadia raw [--options] 命令选项： --enable 是否启用该配置 --updateTaskList 是否更新定时任务 --fileName 指定文件名称 --help 查看此命令帮助 命令帮助： 配置名称 链接地址 [--options] 命令选项 ``` 必须提供配置名称、链接地址，命令选项后需跟选项值 ## 命令选项 [#命令选项] | 名称 | 描述 | 值 | | :----------------: | :---------------------------------: | :--------------: | | `--fileName` | 指定文件名称，需要包含后缀格式，不填则自动截取链接地址中的文件名 | 字符串 | | `--enable` | 是否启用该配置，不提供默认为 `true` | `true` 或 `false` | | `--updateTaskList` | 是否为该配置涉及到的代码文件启用定时任务，不提供默认为 `false` | `true` 或 `false` | | `--help` | 获取命令帮助 | 无 | ```bash showLineNumbers title="命令示例" arcadia raw \ "测试文件" \ "https://raw.githubusercontent.com/User/Repo/refs/heads/main/example.js" \ --enable true \ --updateTaskList true ``` # 添加代码仓库 ```sh title="$ arcadia repo" ❖ Arcadia CLI - 导入代码仓库配置 使用方法： arcadia repo [--options] 命令选项： --enable 是否启用该配置 --isPrivate 是否为私有仓库 --authMethod 私有仓库认证方式，"ssh" 或 "http" --sshAlias 私有仓库 SSH 访问凭据配置 - 配置别名 --sshHostName 私有仓库 SSH 访问凭据配置 - 主机地址 --sshPrivateKeyPath 私有仓库 SSH 访问凭据配置 - 私钥文件路径 --httpUsername 私有仓库 HTTP 访问凭据配置 - 用户名 --httpPassword 私有仓库 HTTP 访问凭据配置 - 密码或令牌 --updateTaskList 是否更新定时任务 --scriptsPath 定时文件路径 --scriptsType 定时文件格式，多个用 "|" 分开 --whiteList 定时文件匹配白名单 --blackList 定时文件匹配黑名单 --autoDisable 是否自动禁用新的定时任务 --addNotify 是否为新增定时任务推送通知提醒 --delNotify 是否为过期定时任务推送通知提醒 --help 查看此命令帮助 命令帮助： 配置名称 链接地址 分支名称 [--options] 命令选项 ``` 必须提供配置名称、链接地址、分支名称，命令选项后需跟选项值 ## 命令选项 [#命令选项] | 名称 | 描述 | 值 | | :-------------------: | :---------------------------------: | :-----------------------------------------------------------------------------: | | `--enable` | 是否启用该配置，不提供默认为 `true` | `true` 或 `false` | | `--isPrivate` | 是否为私有仓库，不提供默认为 `false` | `true` 或 `false` | | `--authMethod` | 私有仓库认证方式 | `ssh` 或 `http` | | `--sshAlias` | 私有仓库 SSH 访问凭据配置 - 配置别名 | 详见 [*authsettings*](/docs/sync/repo#authsettings) | | `--sshHostName` | 私有仓库 SSH 访问凭据配置 - 主机地址 | 详见 [*authsettings*](/docs/sync/repo#authsettings) | | `--sshPrivateKeyPath` | 私有仓库 SSH 访问凭据配置 - 私钥文件路径 | 详见 [*authsettings*](/docs/sync/repo#authsettings) | | `--httpUsername` | 私有仓库 HTTP 访问凭据配置 - 用户名 | 详见 [*authsettings*](/docs/sync/repo#authsettings) | | `--httpPassword` | 私有仓库 HTTP 访问凭据配置 - 密码或令牌 | 详见 [*authsettings*](/docs/sync/repo#authsettings) | | `--updateTaskList` | 是否为该配置涉及到的代码文件启用定时任务，不提供默认为 `false` | `true` 或 `false` | | `--scriptsPath` | 定时文件路径 | 详见 [*cronsettings*](/docs/sync/repo#cronsettings) | | `--scriptsType` | 定时文件格式 | 详见 [*cronsettings*](/docs/sync/repo#cronsettings)，多个用 `\|` 进行分割，例如 `js\|py\|ts` | | `--whiteList` | 定时文件匹配白名单 | 详见 [*cronsettings*](/docs/sync/repo#cronsettings) | | `--blackList` | 定时文件匹配黑名单 | 详见 [*cronsettings*](/docs/sync/repo#cronsettings) | | `--autoDisable` | 是否自动禁用新增定时任务，不提供默认为 `false` | `true` 或 `false` | | `--addNotify` | 是否为新增定时任务推送通知提醒，不提供默认为 `true` | `true` 或 `false` | | `--delNotify` | 是否为过期定时任务推送通知提醒，不提供默认为 `true` | `true` 或 `false` | | `--help` | 获取命令帮助 | 无 | 当选项值包含 `空格` 以及 `;` `&` 等特殊字符时，需用英文引号包裹选项值以避免传递错误 ```bash showLineNumbers title="命令示例" arcadia repo \ "测试仓库" \ "https://github.com/User/Repo.git" \ main \ --enable true \ --updateTaskList true \ --scriptsType 'js|py' \ --whiteList '^test_' ``` # 列出代码文件清单 ```bash arcadia list ``` 查看指定路径下有哪些可以运行的代码文件，可显示代码文件的修改时间和文件大小 `` 相对路径或绝对路径，支持用 `.` 或 `./` 表示当前目录和用 `../` 表示上级目录 # 进程管理 ## 查看进程 [#查看进程] ```bash arcadia ps ``` 查看资源消耗情况和正在运行的代码文件进程，列出的资源包括CPU占用、内存占用、本地文件占用、进程占用 当检测到内存占用较高时会自动尝试释放缓存 ## 清理进程 [#清理进程] ```bash arcadia cleanup ``` 默认杀死距离此刻超过 `6` 小时以上由 `arcadia run` 命令启动的阻塞代码进程，通过此命令可以释放异常占用内存以维护项目稳定运行 ```bash title="指定小时数" arcadia cleanup ``` # 后端服务 目前前端控制面板由后端服务进行托管运行，项目部分功能的实现依赖于后端服务的持续正常运行，所有守护进程服务会由该命令统一管理 ## 开启/重启服务 [#开启重启服务] ```bash arcadia service start ``` 当服务异常时会自动尝试修复 ## 关闭服务 [#关闭服务] ```bash arcadia service stop ``` 项目部分功能依赖后端服务持续运行，请不要长期关闭 ## 查看服务状态信息 [#查看服务状态信息] ```bash arcadia service status ``` 如遇相关服务没有启动或状态异常，在容器初始成功的前提下请先尝试手动启动 ## 重置登录信息 [#重置登录信息] ```bash arcadia service respwd ``` 重置后的用户名和密码均为初始信息 `useradmin` `passwd` # TG Bot ## 启动/重启服务 [#启动重启服务] ```bash arcadia tgbot start ```
正常状态下的日志（点开查看） ```log 2024-00-00 00:00:00,000-telethon.network.mtprotosender-INFO=> [_connect] Connecting to xx.xx.xx.xx:443/TcpFull... 2024-00-00 00:00:00,000-telethon.network.mtprotosender-INFO=> [_connect] Connection to xx.xx.xx.xx:443/TcpFull complete! 2024-00-00 00:00:00,000-tgbot-INFO=> [] loading bot module... 2024-00-00 00:00:00,000-tgbot-INFO=> [load_module] Bot加载-->setshort-->完成 2024-00-00 00:00:00,000-tgbot-INFO=> [load_module] Bot加载-->start-->完成 2024-00-00 00:00:00,000-tgbot-INFO=> [load_module] Bot加载-->sendfile-->完成 2024-00-00 00:00:00,000-tgbot-INFO=> [load_module] Bot加载-->update-->完成 ..... ... . 2024-00-00 00:00:00,000-tgbot-INFO=> [load_module] Bot加载-->help-->完成 ``` 如上，显示各个模块加载完成即表示连接正常，在配置正确的前提下如若一直重复建立连接那可能是网络环境出现了问题
## 停止服务 [#停止服务] ```bash arcadia tgbot stop ``` ## 查看运行日志 [#查看运行日志] ```bash arcadia tgbot logs ``` ## 查看错误日志 [#查看错误日志] ```bash pm2 logs tgbot ``` ## 更新升级 [#更新升级] ```bash arcadia tgbot update ``` 使用本地最新源码重装 执行安装操作后底层代码目前仅支持无缝迁移 **tgbot/diy** 目录下的用户文件，请注意提前备份你放置在 **tgbot** 目录下除 **tgbot/diy** 子目录以外的其它重要文件 # 推送通知 ```bash arcadia notify <content> [type] ``` | 参数 | 必填 | 说明 | | ------- | -- | -------------------------------------------------- | | title | 是 | 消息标题 | | content | 是 | 消息内容 | | type | 否 | 消息类型，默认 `info`，可选值：`info`、`warn`、`error`、`success` | # 清理日志 ```bash arcadia rmlog ``` 默认保留 `7` 天以内的日志文件，该默认保留天数由用户配置控制，关于如何修改详见控制面板《个人设置 - 通用》历史数据清理 `代码文件运行日志（保留天数）`。 ```bash title="删除存在超过指定天数的日志" arcadia rmlog <days> ``` <Callout type="idea" title="友情提示"> 平台内置了一个自动清理历史数据的定时任务，该定时任务包含此部分内容，因此你一般无需手动执行该命令。 </Callout> # 更新代码同步配置 # 更新代码同步配置 [#更新代码同步配置] ```bash arcadia update <args> ``` | 子命令 | 含义 | 描述 | | :-----: | :------: | ---------------------- | | `repo` | 更新全部代码仓库 | 更新所有位于 `repo` 目录下的代码仓库 | | `raw` | 更新代码文件 | 更新所有位于 `raw` 目录下的代码文件 | | `extra` | 运行额外更新脚本 | 运行用户自定义的更新脚本 | ## 更新全部代码同步配置 [#更新全部代码同步配置] ```bash arcadia update sync ``` 更新除指定仓库以外的所有内容 ## 更新指定配置或指定路径下的代码仓库 [#更新指定配置或指定路径下的代码仓库] ```bash arcadia update <name/path> ``` ·`<name> 配置名称`，`<path>` 仓库的相对路径或绝对路径，支持用 `.` 或 `./` 表示当前目录和用 `../` 表示上级目录 ## 常见更新报错 [#常见更新报错] * `ssh: connect to host gitee.com port XXX: Connection timed out` 当前宿主机的 `XXX` 端口不可用所导致的网络连通性问题 * `Could not resolve hostname XXXX: Temporary failure in name resolution lost connection` 字面意思，表示无法解析到该 `XXXX` 域名服务器，说明网络环境异常 * `Repository more than 5 connections` 原因在于 `Gitee` 的服务器限制每秒最多同时连接 `5` 个客户端，此报错为正常现象稍后再次尝试即可 # 更新 Arcadia ```bash arcadia upgrade ``` 同步最新的源代码，更新时长受版本变动大小、下载速度等因素影响 可以在前端控制面板《个人设置 - 关于》页面进行一键更新 # Env 环境变量 目前为环境变量设计了三种类型，如果你还不理解这三种类型的区别请先参考[此描述](/docs/configuration#1-环境变量--控制面板)并了解前端界面设计\ 为了提高开发效率已将部分接口的传参设计为了更容易理解的形式，建议使用前先学习项目[数据模型](/docs/api/env/schema)设计 <DocsCategory /> # 更改状态 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 创建 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 删除 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 调整排序 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 分页查询 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 全局查询 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 精准查询 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 查询复合变量(组)的成员 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 获取所有标签 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 更新 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Exec 命令执行 <DocsCategory /> # 执行 Shell 命令 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 执行 Shell 命令（Stream） {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 运行代码文件 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 终止运行代码文件 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 运行代码文件（Stream） {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 查询运行状态 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # File 文件系统 <DocsCategory /> # 获取文件内容 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 保存文件内容 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 创建 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 删除 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 下载 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 查询属性 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 获取文件列表 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 移动 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 重命名 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 上传 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Message 消息中心 消息中心提供统一的消息推送与管理能力，通过 OpenAPI 可以向平台推送用户消息，便于外部系统集成通知功能。 <Callout type="warn"> 根据业务设定，该系列API仅能操作推送到消息中心的用户个人消息，无法操作其它内部消息。 </Callout> <DocsCategory /> # 推送消息 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 删除消息 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 获取消息详情 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 分页查询 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 更新全部消息已读状态 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 更新消息已读状态 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 获取未读消息计数 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Cron 定时任务 <DocsCategory /> # 创建 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 删除 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 调整排序 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 分页查询 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 查询 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 运行任务 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 查询运行中的任务 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 获取标签列表 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 终止任务 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 更新 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 代码仓库 通过克隆仓库 `Git` 的方式扩展本地脚本，存放在 `/arcadia/repo` 目录下 ## 主配置项 [#主配置项] <TypeTable type="{ name: { description: '代码仓库名称', type: 'string', default: '""', required: true, }, url: { description: '代码仓库地址', type: 'string', default: '""', required: true, }, branch: { description: '分支名称', type: 'string', default: '""', required: true, }, enable: { description: '是否启用该配置', type: 'boolean', default: 'true', required: false, }, isPrivate: { description: '是否为私有仓库', type: 'boolean', default: 'true', required: false, }, authSettings: { description: '私有仓库访问凭据配置（详见下方）', type: 'object', default: '{}', required: false, }, cronSettings: { description: '定时任务导入配置（详见下方）', type: 'object', default: '{}', required: false, }, }" /> <Tabs items="['cronSettings', 'authSettings']"> <Tab id="cronSettings" value="cronSettings"> <TypeTable type="{ updateTaskList: { description: '是否为该配置涉及到的代码文件启用定时任务', type: 'boolean', default: 'false', required: false, }, scriptsPath: { description: '定时文件路径，默认为空代表仓库根目录', type: 'string', default: '""', required: false, }, scriptsType: { description: '定时文件格式', type: 'string[]', default: '["js", "py", "ts"]', required: false, }, whiteList: { description: '定时文件匹配白名单，默认为空即所有文件', type: 'string', default: '""', required: false, }, blackList: { description: '定时文件匹配黑名单，默认为空', type: 'string', default: '""', required: false, }, autoDisable: { description: '是否自动禁用新增定时任务', type: 'boolean', default: 'false', required: false, }, addNotify: { description: '是否为新增定时任务推送通知提醒', type: 'boolean', default: 'true', required: false, }, delNotify: { description: '是否为过期定时任务推送通知提醒', type: 'boolean', default: 'true', required: false, }, }" /> * 关于 `scriptsPath` 根据导入工作原理，匹配文件不会递归仓库下的所有目录，不设置该项或键值为空即代表默认根目录 如果你想配置匹配指定目录下的文件则需要手动配置，多个路径需要使用空格来进行分割，仓库根目录用 `/` 来表示 ```yaml title="示例" scriptsPath: "/ test" ``` 如上，最终会匹配位于仓库根目录和 `test` 子目录下的所有文件即 `/arcadia/repo/<repo_dir>/*` 和 `/arcadia/repo/<repo_dir>/test/*` * 关于 `scriptsType` 你需要通过数组的形式进行配置，键名为文件后缀格式名称，默认（不填）为 Node.js、Python、TypeScript ```yaml title="示例" scriptsType: - js - py - ts ``` 工作原理是在读取该项配置时会使用 `join()` 方法将数组合并成一个用空格进行分割的字符串 `js py ts`，之后会通过遍历数组的方式转变成基于 [**grep**](https://www.runoob.com/linux/linux-comm-grep.html) 指令过滤规则的最终形态字符串 `\.js$|\.py$|\.ts$` * 关于 `whiteList` 或 `blackList` <Callout> 如果你启用了定时文件配置那么请尽可能不要忽略此配置项，因为如果不配置该项可能会导致自动添加一些无用的定时任务 </Callout> 基于 [**grep**](https://www.runoob.com/linux/linux-comm-grep.html) 指令进行过滤（默认使用 `-E` 命令选项用于匹配多个表达式），支持正则表达式。如果要匹配多个表达式，那么根据该指令规范你需要使用 `|` 字符来进行分割，你可以先在本地调试好再进行配置，例如 `ls | grep -E "<xxx>"`。如果你想学习正则表达式和该指令你可以看看 [《基础正则表达式》](https://www.junmajinlong.com/shell/regex_basic) 这篇文章 <Callout title="为什么需要使用单引号包裹键值？"> 根据 YAML 语法规范，如果使用双引号来包裹键值那么会使转义字符生效，这样在读取与过滤规则相关的键值对时会出现问题 </Callout> </Tab> <Tab id="authSettings" value="authSettings"> <TypeTable type="{ method: { description: '认证方式，需填写固定值 ssh 或 http', type: "'ssh' | 'http'", typeDescription: '固定值 ssh 和 http 分别代表 sshConfig 和 httpAuth 两种认证方式', default: '""', required: true, }, sshConfig: { description: 'SSH认证配置（详见下方）', type: 'object', default: '{}', required: false, }, httpAuth: { description: 'HTTP认证配置（详见下方）', type: 'object', default: '{}', required: false, }, }" /> <Tabs items="['SSH 配置', 'HTTP 认证']"> <Tab id="sshConfig" value="SSH 配置"> <TypeTable type="{ alias: { description: '配置别名（此处每个仓库需要使用独特的名称，不支持中文字符，尽量不要使用特殊字符）', type: 'string', required: true, }, hostName: { description: '主机地址，例如 github.com', type: 'string', required: true, }, privateKeyPath: { description: '私钥文件全局路径（建议放在用户配置文件目录下即 /arcadia/config/xxx ）', type: 'string', required: true, }, }" /> SSH 配置需要用户自行上传私钥 </Tab> <Tab id="httpAuth" value="HTTP 认证"> <TypeTable type="{ username: { description: '用户名', type: 'string', required: true, }, password: { description: '密码或令牌', type: 'string', required: true, }, }" /> 部分代码托管平台例如 `GitHub` 取消了通过账号密码对私有仓库的访问\ 届时仅支持令牌访问，具体创建令牌的方法详见 [管理个人访问令牌](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) </Tab> </Tabs> 认证方式二选一，不要同时配置 </Tab> </Tabs> ## 填法示例 [#填法示例] ```yaml repo: - name: 仓库1 url: 'https://github.com/User1/Repo1.git' branch: main enable: true isPrivate: false cronSettings: updateTaskList: true autoDisable: false addNotify: true delNotify: true scriptsPath: '' scriptsType: - js whiteList: '' blackList: '' - name: 仓库2 url: 'https://gitlab.com/User2/Repo2.git' branch: master enable: true isPrivate: true authSettings: method: ssh sshConfig: alias: Repo2 hostName: gitlab.com privateKeyPath: /arcadia/config/repo2_rsa ``` 配置好后你需要执行 `arcadia update repo` 命令来使该配置生效 <Callout title="如何修改已配置仓库的远程链接地址？"> 针对同一个仓库直接修改 `url` 键值对即可，同一个仓库指的是两个不同的地址所指向的仓库拥有相同的用户名和仓库名，否则将被视为一个新的仓库 </Callout> <Callout type="idea" title="友情提示"> 大部分代码仓库都托管于 [GitHub](https://github.com) 上，如果你的设备不能有效与其连通则需要使用代理 </Callout> ## 删除仓库配置 [#删除仓库配置] 仅删除代码仓库配置并不能完全从 Arcadia 平台中移除该仓库的相关数据，所以如果你想彻底删除它们请进行下列操作 * 删除代码同步配置文件中的仓库配置 * 删除相关定时任务，你可以通过控制面板的定时任务页进行操作，在任务名称列设置过滤后批量删除 * 删除找到位于 `/arcadia/repo` 目录下的实际仓库目录，目录名格式为 `作者名_仓库名` ## 关于定时任务 [#关于定时任务] 根据工作原理，你可能会遇到下方提到的特殊情况，你应该了解这些情况并且知道如何解决 1. 修改定时过滤规则并不会影响已经添加的定时任务，所以如果有不合适的定时任务则需要你手动进行删除。 2. 匹配定时任务仅支持处理基于文件增删变动的情况，这意味着如果在首次克隆仓库之后再配置启用仓库定时任务是无效的，因为没有检测到文件变动。 ### 重新导入定时任务 [#重新导入定时任务] 有时候你想按照新的规则进行重新导入定时任务，可以按顺序进行下列操作实现： 1\). 进入控制面板《定时任务 - 任务配置》页面，切换到表格视图，在任务名称列的过滤按钮处选中目标仓库，之后点击全选 - 批量操作 - 删除\ 2\). 找到位于 `/arcadia/repo` 目录下的实际仓库目录并将其删除，目录名格式为 `作者名_仓库名`\ 3\). 同步目标仓库配置或执行 `arcadia update repo` 命令，之后会重新克隆仓库并导入定时任务 <Callout icon="false"> 此操作除了会删除仓库的本地文件目录数据以外，还会覆盖你之前手动修改过的定时任务数据，包括任务执行命令、定时规则、高级配置等，建议最好从一开始就确定使用需求。 </Callout> ## 快速添加配置 [#快速添加配置] 详见 CLI 文档教程 [添加代码仓库配置](/docs/cli/config/repo) # 代码文件 通过下载文件 `Wget` 的方式扩展本地脚本，存放在 `/arcadia/raw` 目录下 ## 环境配置项 [#环境配置项] | 名称 | 必填 | 类型 | 默认值 | 描述 | | :------------: | :-: | :-------: | :----: | -------------------------------- | | `name` | 是 | `string` | 无 | 代码文件名称 | | `url` | 是 | `string` | 无 | 代码文件地址 | | `fileName` | 否 | `string` | 无 | 指定文件名称，需要包含后缀格式，不填则自动截取链接地址中的文件名 | | `enable` | 否 | `boolean` | `true` | 是否启用该配置 | | `cronSettings` | 否 | `object` | 无 | 定时任务设置 | * cronSettings <TypeTable type="{ updateTaskList: { description: '是否为该配置涉及到的代码文件启用定时任务', type: 'boolean', default: 'false', required: true, }, }" /> ## 填法示例 [#填法示例] ```yaml raw: - name: Repo1 url: 'https://github.com/User1/Repo1/raw/master/example.js' cronSettings: updateTaskList: true - name: Repo2 url: 'https://github.com/User2/Repo2/raw/master/template.py' - name: Repo3 url: 'https://github.com/User3/Repo3/raw/master/example.js' fileName: 'repo3_example.js' ``` 配置好后你需要执行 `arcadia update raw` 命令来使该配置生效 导入前请先确认目标代码文件中的备注内容中是否含有 `Cron 表达式` ，如若没有或者未识别到那么将随机指定一个每天执行一次的定时规则 <Callout type="idea" title="友情提示"> 大部分脚本都位于 [GitHub](https://github.com) 仓库上，如果你的设备不能有效与其连通可以尝试使用 CDN 进行加速例如 [jsDelivr](https://www.jsdelivr.com/github)，不过更新可能会因为缓存而存在一定的延迟 </Callout> ## 配置依赖文件 [#配置依赖文件] 根据配置代码文件的原理，对应**raw**目录下只允许存在已配置的脚本，配置以外的文件会被删除，如果运行此处的脚本需要额外的依赖文件那么你需要配置此项 ```yaml gobal: rawDependencyFilter: '' # string ``` 基于 [**grep**](https://www.runoob.com/linux/linux-comm-grep.html) 指令进行过滤（默认使用 `-E` 命令选项用于匹配多个表达式），支持正则表达式。如果要匹配多个表达式，那么根据该指令规范你需要使用 `|` 字符来进行分割，与代码仓库的定时任务黑白名单配置用法相同 ## 删除已配置的代码文件 [#删除已配置的代码文件] 删除配置文件中的相关配置项即可，在更新后会自动删除脚本和定时，无需手动删除 ## 快速添加配置 [#快速添加配置] 详见 CLI 文档教程 [添加代码文件配置](/docs/cli/config/raw) # 守护进程 <Callout type="idea" title="使用须知"> 该命令目前主要服务于后端且仅用于任务启动，请优先通过控制面板进行持久化创建与管理，否则任务将无法在控制面板中显示。 </Callout> <Callout type="info" title="什么是守护进程？"> 守护进程是可以周期运行的特殊进程，在这里指的是将代码文件设置为后台进程循环运行，当代码文件运行结束或中断时会自动重新运行，适用于需要长期连续运行的代码文件。\ 针对同一个代码文件只可存在一个守护进程，这就意味着当即将被运行的代码文件存在多个任务时不允许设置守护进程。 </Callout> 守护进程模式使用独立的 `rund` 子命令，通过 PM2 将代码文件保持在后台持续运行，进程退出或崩溃后会自动重新拉起。 ```sh title="$ arcadia run" ❖ Arcadia CLI - 运行代码文件（守护进程） 使用方法： arcadia rund <name/path> [--options] 专属命令选项： --name 指定任务名称 --max-restarts 指定最大重启次数 --restart-delay 指定重启延迟毫秒数 --log-file 指定日志文件路径 --restart-cron 指定重启计划任务 --no-autorestart 禁用进程崩溃后的自动重启 --max-memory-restart 内存超出指定值时自动重启（例如 200M） --stop-exit-codes 指定不触发自动重启的退出码 --exp-backoff-restart-delay 启用指数退避重启，指定初始延迟毫秒数 通用命令选项： -s, --silent 静默运行 - 不推送任何通知消息 -a, --agent 网络代理 - 为 JavaScript 和 TypeScript 代码文件启用全局 HTTP/HTTPS 代理，配置方法详见文档 -r, --recombine-env 变量重组 - 按照指定顺序重新组合复合变量的值，选项后需跟变量名称、分隔符、重组表达式 表达式语法：多个值用 "," 隔开，值区间用 "-" 连接，可以用 "%" 表示值的总数 -E, --exec-args 执行参数 - 将该选项后面的内容作为参数传递给代码执行器 -- 传递选项，将该选项后面的所有内容都作为选项参数传递给代码文件 --deno，--use-deno 使用 Deno 运行时 --bun，--use-bun 使用 Bun 运行时 --node，--use-node 使用 Node.js 运行时 --tsx，--use-tsx 使用 tsx 执行 --ts-node，--use-ts-node 使用 ts-node 执行 命令帮助： <name> 文件名(仅scripts目录) <path> 相对路径或绝对路径 [--options] 命令选项 ``` ## 配置选项 [#配置选项] 支持部分通用命令选项，同时提供下列守护进程专属命令选项 | 选项 | 选项值 | 描述 | | :---------------------------: | :-: | -------------------------- | | `--name` | ✓ | 指定 PM2 进程名称，默认使用代码文件名 | | `--max-restarts` | ✓ | 最大自动重启次数（非负整数），默认无限制 | | `--restart-delay` | ✓ | 崩溃后重启延迟毫秒数（非负整数），默认 `0` | | `--log-file` | ✓ | 日志文件完整路径，未指定时使用项目默认日志目录 | | `--restart-cron` | ✓ | 定时重启 Cron 表达式，为空则不启用 | | `--no-autorestart` | | 禁用崩溃自动重启，进程退出后不再重新拉起 | | `--max-memory-restart` | ✓ | 内存超限自动重启阈值（如 `200M`），默认不启用 | | `--stop-exit-codes` | ✓ | 遇到指定退出码时停止重启（非负整数，如 `0`） | | `--exp-backoff-restart-delay` | ✓ | 启用指数退避重启策略，指定初始延迟毫秒数（非负整数） | ## 管理方法 [#管理方法] * 查看有哪些守护进程正在运行 `pm2 list` * 停止运行 `pm2 stop <任务名>` * 删除任务 `pm2 delete <任务名>` 默认存在二个项目内置的服务 `arcadia_server` `tgbot`，请不要删除它们其中的任何一个 # 运行代码文件 <Callout type="info" icon="false"> 前端控制面板《代码编辑》页面中的运行代码文件功能以及代码同步功能自动导入定时任务的运行命令均基于该命令实现 </Callout> ✍在本篇内容中你将学习到如何运行代码文件这一基础功能。看上去内容很多？其实非常简单。 需要特别说明的是，代码文件是各编程语言程序文件的统称，并非所有代码文件都属于脚本类型。 ```sh title="$ arcadia run" ❖ Arcadia CLI - 运行代码文件 使用方法： arcadia run <name/path/url> [--options] 命令选项： -l, --loop 循环运行 - 连续多次的执行代码文件，选项后需跟循环次数 -s, --silent 静默运行 - 不推送任何通知消息 -w, --wait 推迟执行 - 等待指定时间后再运行任务，选项后需跟时间值 -D, --delay 延迟执行 - 随机倒数一定秒数后再执行代码文件 -a, --agent 网络代理 - 为 JavaScript 和 TypeScript 代码文件启用全局 HTTP/HTTPS 代理，配置方法详见文档 -T, --timeout 运行超时 - 设置运行任务超时机制，选项后需跟 timeout 指令的参数作为选项值 -N, --no-log 禁用日志 - 不记录代码运行日志 -p, --proxy 启用下载代理 - 仅适用于执行位于 GitHub 仓库的代码文件，代理固定为 jsDelivr CDN -c, --concurrent 并发运行 - 默认运行1个任务，若想增加运行任务数量那么请传参任务数量 -t, --thread 并发线程数 - 指定同时运行的最大任务数量，选项后需跟正整数，需与并发运行同时使用 -b, --background 后台运行 - 不在前台输出代码执行进度，不占用终端命令行 -r, --recombine-env 变量重组 - 按照指定顺序重新组合复合变量的值，选项后需跟变量名称、分隔符、重组表达式 ㅤ 表达式语法：多个值用 "," 隔开，值区间用 "-" 连接，可以用 "%" 表示值的总数 -R, --recombine-env-group 分组运行 - 为每组变量单独运行，是变量重组的扩展，传参基本一致，其中重组表达式内用 "@" 来区分不同组 -S, --split-env 拆分运行 - 将复合变量的值拆分后为每个值声明变量并单独运行代码文件，选项后需跟需要拆分的变量名称、分隔符 -E, --exec-args 执行参数 - 将该选项后面的内容作为参数传递给代码执行器 -- 传递选项 - 将该选项后面的所有内容都作为选项参数传递给代码文件 --deno，--use-deno 使用 Deno 运行时 --bun，--use-bun 使用 Bun 运行时 --node，--use-node 使用 Node.js 运行时 --tsx，--use-tsx 使用 tsx 执行 --ts-node，--use-ts-node 使用 ts-node 执行 沙箱： --sandbox 沙箱模式，在受限环境中运行代码 --sandbox-net-allow <spec> 出站白名单，仅放行匹配的出站连接，可多次使用，与黑名单选项互斥 --sandbox-net-deny <spec> 出站黑名单，屏蔽匹配的出站连接，可多次使用，与白名单选项互斥 --sandbox-net-deny-all 完全断网，阻断所有出站连接，与其它出站控制选项互斥 --sandbox-net-deny-local 屏蔽局域网与本机，可与黑名单选项叠加使用，与白名单选项、完全断网选项互斥 --sandbox-net-allow-bind <port> 允许绑定指定端口，放行 TCP 服务端监听，可多次使用 --sandbox-net-allow-bind-all 允许绑定任意端口，放行 TCP 服务端监听 --sandbox-http-allow <rule> HTTP 请求白名单，仅放行匹配的 HTTP/HTTPS 请求，可多次使用，与黑名单选项互斥 --sandbox-http-deny <rule> HTTP 请求黑名单，屏蔽匹配的 HTTP/HTTPS 请求，可多次使用，与白名单选项互斥 --sandbox-max-memory <size> 内存上限（例如 512M、1G） --sandbox-clear-env 清空环境变量，仅保留最小系统路径 --sandbox-env KEY=VALUE 注入环境变量，可多次使用 --sandbox-allow-env-whitelist VAR1,VAR2 环境变量白名单，仅保留指定变量（隐式清空） --sandbox-allow-env-blacklist VAR1,VAR2 环境变量黑名单，排除指定变量 --sandbox-allow-read <path> 追加只读目录，可多次使用 --sandbox-allow-write <path> 追加读写目录，可多次使用 --sandbox-opts <args> 透传底层参数给沙箱引擎，可多次使用 命令帮助： <name> 文件名(仅scripts目录) <path> 相对路径或绝对路径 <url> 链接地址 [--options] 命令选项 ``` <DocsCategory /> # 使用方法 ```bash arcadia run <name/path/url> [--options] ``` ### 文件名称 `name` [#文件名称-name] 仅限 `scripts` 个人目录下的代码文件，并且仅涵盖 `根目录`，你可以把你常用的代码文件（脚本）存放在这里 ### 路径 `path` [#路径-path] 相对路径或绝对路径，支持使用 `.` 或 `./` 作为当前目录和用 `../` 作为上级目录，如果运行本地的个人代码文件则可以省略路径\ 如果运行的是已配置的代码仓库中的代码文件可以使用相对路径，例如 `/arcadia/repo/<仓库目录名称>/example.js` 可以使用 `repo/example.js` 替代 ### 链接地址 `<url>` [#链接地址-url] 运行后代码文件默认保存在 `scripts` 个人目录，支持链接自动纠正功能\ 链接自动纠正功能是当拉取位于远程托管仓库的代码文件时可自动将 *blob* 链接转换为 *raw* 原始文件链接，此功能已应用到整个项目 ### 命令选项 `[--options]` [#命令选项---options] 用于实现一些扩展功能，具体请查看下方的文档内容 *** ## 基础概念 [#基础概念] <Accordions type="multiple"> <Accordion title="关于日志存储" id="关于日志存储"> 默认情况下代码文件在运行后会自动将日志存放在 **log** 目录下的文件夹内，会以目录的形式进行分类 目录名中的主要组成部分是代码文件名称，用户导入代码文件的日志目录名称为`<仓库名/raw>_文件名去后缀`，中间用下划线分割 </Accordion> <Accordion title="支持直接运行的代码文件类型" id="支持直接运行的代码文件类型"> 目前支持的代码文件类型有 `js` `mjs` `cjs` `py` `.ts` `.cts` `.mts` `go` `lua` `rb` `rs` `pl` `c` `sh`，项目已默认预装了 `JavaScript`、`Python`、`Perl` 的运行环境 当运行本地代码文件时，文件名的后缀格式（代码文件类型）可以省略，届时将启用模糊查找，优先级为 `JavaScript` > `Python` > `TypeScript` > `Go` > `Lua` > `Ruby` > `Rust` > `Perl` > `C` > `Shell`，当存在同名代码文件时仍适用此规则 </Accordion> <Accordion title="关于运行代码文件所需的依赖" id="关于运行代码文件所需的依赖"> 这部分内容与项目命令无关，用于解决代码文件运行时缺少第三方依赖库报错的问题，具体详见 [运行环境](/docs/environment#解决依赖) 文档 </Accordion> </Accordions> *** ## 命令选项 [#命令选项] 使用方法：追加在命令的末尾，熟练后可以使用简写 > 一个高级的应用程序CLI指令往往有着复杂的命令选项设计，这可能是一个漫长的学习过程\~ | 选项 | 用途 | 选项值 | 描述 | | :---------------------------: | :----------------------------------------: | :-: | ---------------------------------------------------------------------------------------------------------- | | `-l`, `--loop` | 循环运行 | ✓ | 连续多次运行代码文件，选项后需跟 *循环次数(正整数)*，该选项与 **等待执行** 和 **延迟执行** 参数同时使用时仍然有效互不干涉 | | `-s`, `--silent` | 静默运行 | | 静默运行任务不推送任何通知消息 | | `-w`, `--wait` | 推迟执行 | ✓ | 等待指定时间后再运行代码文件，选项后需跟 *等待时间单位* 作为参数值，具体参照 [sleep](https://www.runoob.com/linux/linux-comm-sleep.html) 命令的用法 | | `-D`, `--delay` | 延迟执行 | | 随机倒数一定秒数后再运行代码文件，该秒数上限可以在配置文件中定义 | | `-a`, `--agent` | 网络代理 | | 为 JavaScript 和 TypeScript 代码文件启用全局 HTTP/HTTPS 代理，使用方法详见下方说明 | | `-T`, `--timeout` | 运行超时 | ✓ | 设置运行任务超时机制，选项后需跟 [timeout](https://www.coonote.com/linux/linux-cmd-timeout.html) 指令的参数作为选项值 | | `-N`, `--no-log` | 禁用日志 | | 不记录代码运行日志 | | `-p`, `--proxy` | 启用下载代理 | | 仅适用于执行位于 GitHub 仓库的代码文件，该代理固定为 [jsDelivr](https://www.jsdelivr.com/?docs=gh) 公共 CDN 加速代理 | | `-c`, `--concurrent` | 并发运行 | | 默认运行1个任务，若想增加运行任务数量那么请传参 `任务数量(正整数)` | | `-t`, `--thread` | 指定并发线程 | ✓ | 指定同时运行的最大任务数量，选项后需跟正整数，需与并发运行同时使用 | | `-b`, `--background` | 后台运行 | | 不在前台输出代码执行进度，不占用终端命令行 | | `-r`, `--recombine-env` | 变量重组 | ✓ | 按照指定顺序重新组合复合变量的成员值，选项后需跟变量名称、分隔符、重组表达式。表达式语法：多个值用 `,` 隔开，值区间用 `-` 连接，可以用 `%` 表示值的总数 | | `-R`, `--recombine-env-group` | 分组运行 | ✓ | 基于变量重组功能上的扩展应用，为每组变量单独运行代码文件，传参与变量重组功能基本一致，其中重组表达式内用 `@` 来区分不同组 | | `-S`, `--split-env` | 拆分运行 | ✓ | 将复合变量的成员值拆分后为每个值声明变量并单独运行代码文件，选项后需跟需要拆分的变量名称、分隔符 | | `-E`, `--exec-args` | 执行参数 | ✓ | 将该选项后面的内容作为参数传递给代码执行器 | | `--` | 传递选项 | ✓ | 将该选项后面的所有内容都作为选项参数传递给代码文件 | | `--deno`, `--use-deno` | [Deno](https://deno.com) | | 使用 Deno 运行时 | | `--bun`, `--use-bun` | [Bun](https://bun.sh) | | 使用 Bun 运行时 | | `--node`, `--use-node` | [Node.js](https://nodejs.org) | | 使用 Node.js 运行时 | | `--tsx`, `--use-tsx` | [TypeScript Execute (tsx)](https://tsx.is) | | 使用 tsx 执行 | | `--ts-node`, `--use-ts-node` | [ts-node](https://typestrong.org/ts-node) | | 使用 ts-node 执行 | <Accordions type="multiple"> <Accordion title="如何区分并发运行与后台运行？" id="如何区分并发运行与后台运行"> 通俗易懂的来说并发就是同一时间启动多个任务在后台运行，所以这意味着运行单个任务时使用并发运行命令选项是无意义的行为。\ 这两个命令选项的作用实际上是等价的，为了便于理解才分开设计，你需要加强对功能的理解以作出正确的选择判断。 项目命令会根据运行的任务数量动态检测使用场景，届时会判定一些无意义的操作从而报错跳出。\ 例如分组运行和拆分运行就是多任务类型，你应该使用并发运行而不是后台运行。 </Accordion> <Accordion title="关于并发任务的一些注意事项" id="关于并发任务的一些注意事项"> 在并发运行代码文件时，会将每个任务的运行日志存储在独特的日志文件中，文件名会使用特殊的标记以进行区分，具体规则如下： * `g<index>` 代表分组运行时的标记、`e<index>` 代表拆分运行时的标记、`t<index>` 表示并发任务数 <Callout type="idea"> 默认为全量并发，请合理使用避免对系统造成的压力过大，可以指定并发线程数来限制同时运行的最大任务数量 </Callout> </Accordion> <Accordion title="关于重组表达式的应用示例" id="关于重组表达式的应用示例"> <Callout> 在 Linux 系统命令行中有一些特殊的字符，例如 `;` `&` 等。如果目标复合变量的分隔符包含这些特殊字符，届时需用英文引号包裹以避免传递错误 </Callout> 接下来是一些示例用法，以 `example.js` 脚本和 `TEST_CONFIG` 配置变量为例，其中 `TEST_CONFIG` 为复合变量且分隔符为 `@` ```bash title="1. 指定第1个和第3个配置" arcadia run example.js -r TEST_CONFIG @ 1,3 ``` ```bash title="2. 指定第1个至第5个配置" arcadia run example.js -r TEST_CONFIG @ 1-5 ``` ```bash title="3. 倒序加载所有配置" arcadia run example.js -r TEST_CONFIG @ %-1 ``` ```bash title="4. 以第1个和第2个、第3个至第5个配置为两组分别运行" arcadia run example.js -R TEST_CONFIG @ 1,2@3-5 ``` </Accordion> <Accordion title="关于执行参数和传递选项的区别" id="关于执行参数和传递选项的区别"> 可以简单理解为 `<执行器指令> <执行参数> <目的代码文件> <传递选项>`，例如 `node <执行参数> example.js <传递选项>` 另外需要注意的是 `执行参数` 选项后跟的是一个选项值，例如 `ad run example.js --exec-args "-T --verbose"`，而传递选项会将该选项后的全部内容解析为要传递的参数内容，可以是多个选项，例如 `ad run example.js -- args1 args2`... </Accordion> <Accordion title="关于如何使用网络代理命令选项" id="关于如何使用网络代理命令选项"> 该功能由 [global-agent](https://www.npmjs.com/package/global-agent) 实现 首先需要全局安装该依赖包，请自行在控制面板《环境配置 - 依赖管理》页面添加模块：生态 `npm`、包名 `global-agent@3` 然后需要配置 `GLOBAL_AGENT_HTTP_PROXY` 环境变量，更多使用方法详其官方文档 </Accordion> </Accordions> # 隔离运行（沙箱） > 该功能目前处于实验性 ```bash arcadia run <name/path/url> --sandbox ``` <Callout icon="false"> 沙箱模式仍支持使用 `arcadia stop` 终止运行中的代码文件，但不支持守护进程 `arcadia rund` 模式。 </Callout> ### 什么是沙箱？ [#什么是沙箱] 沙箱是一种将代码进程放入受限独立环境中运行的隔离机制。启用后，代码只能访问自身文件目录和必要的系统运行库，除这些路径外无法读取其它目录中的文件，也无法调试其它进程。特别适合运行来自不可信来源的代码文件。 此功能由 [Sandlock](https://github.com/multikernel/sandlock) 驱动，Arcadia CLI 仅作为 Sandlock 的包装器，沙箱已成为 AI Agent 运行的默认环境配置。 ### 预设配置 [#预设配置] 启用沙箱功能后，代码进程将按以下预设配置运行，这是沙箱的基准隔离状态，可通过下方的自定义配置选项进一步调整： * **文件系统**：仅可读写代码文件所在目录与 `/tmp`，可读取系统运行库等只读挂载，其余目录不可访问 * **网络**：默认禁止访问本机与内网地址，公网访问正常 * **端口绑定**：默认禁止监听任何端口 * **环境变量**：全量继承当前运行环境的所有变量，与正常运行一致 * **进程可见性**：与宿主共享 PID 命名空间，`/proc` 中仍可见宿主进程；沙箱通过 seccomp 阻断对其它进程的调试等危险操作 ### 自定义配置项 [#自定义配置项] > 以下选项均需配合 `--sandbox` 使用，用于在预设配置基础上进行自定义调整。 | 选项 | 选项值 | 描述 | | :-----------------------------: | :-: | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `--sandbox-net-allow` | ✓ | 出站白名单，仅放行匹配规则的出站连接（指定后取代默认网络预设），可多次使用，与其余出站控制选项互斥 | | `--sandbox-net-deny` | ✓ | 出站黑名单，在默认屏蔽本地的基础上追加屏蔽匹配规则的出站连接，可多次使用，可与 `--sandbox-net-deny-local` 叠加，与 `--sandbox-net-allow`、`--sandbox-net-deny-all` 互斥 | | `--sandbox-net-deny-all` | | 完全断网，阻断所有出站网络连接，与其余出站控制及 HTTP 过滤选项互斥（端口绑定不受影响） | | `--sandbox-net-deny-local` | | 屏蔽局域网与本机，阻断本地回环、私网网段及云元数据地址段（`169.254.0.0/16`）及 IPv6 回环、ULA、链路本地地址，可与 `--sandbox-net-deny` 叠加，与 `--sandbox-net-allow`、`--sandbox-net-deny-all` 互斥 | | `--sandbox-net-allow-bind` | ✓ | 允许绑定指定 TCP 端口，支持端口列表与区间（如 `8080`、`8080,9000-9005`），与出站控制独立，可多次使用 | | `--sandbox-net-allow-bind-all` | | 允许绑定任意端口，放行所有 TCP 端口绑定监听，与 `--sandbox-net-allow-bind` 互斥 | | `--sandbox-http-allow` | ✓ | HTTP 请求白名单，仅放行匹配的 HTTP/HTTPS 请求（格式：`"METHOD host/path"`），可多次使用，与 `--sandbox-http-deny` 互斥 | | `--sandbox-http-deny` | ✓ | HTTP 请求黑名单，屏蔽匹配的 HTTP/HTTPS 请求（格式：`"METHOD host/path"`），可多次使用，与 `--sandbox-http-allow` 互斥 | | `--sandbox-max-memory` | ✓ | 内存上限，限制进程最大内存用量，支持 `M`（兆字节）和 `G`（吉字节）单位（不区分大小写） | | `--sandbox-clear-env` | | 清空环境变量，移除所有继承的环境变量（仅保留最小系统路径），可配合 `--sandbox-env` 补充注入 | | `--sandbox-env` | ✓ | 注入环境变量，向进程追加自定义环境变量（`KEY=VALUE`），可多次使用 | | `--sandbox-allow-env-whitelist` | ✓ | 环境变量白名单，仅保留逗号分隔的指定变量（隐式启用清空），与 `--sandbox-clear-env` 互斥 | | `--sandbox-allow-env-blacklist` | ✓ | 环境变量黑名单，排除逗号分隔的指定变量（其余正常继承），与 `--sandbox-clear-env`、`--sandbox-allow-env-whitelist` 互斥 | | `--sandbox-allow-read` | ✓ | 允许只读访问，在预设挂载之外追加只读目录，可多次使用 | | `--sandbox-allow-write` | ✓ | 允许读写访问，在预设挂载之外追加读写目录，可多次使用 | | `--sandbox-opts` | ✓ | 透传底层参数，将原始参数直接传递给 sandlock（选项名与值写在同一字符串内），可多次使用 | ### 使用示例 [#使用示例] <Accordions type="multiple"> <Accordion title="基础沙箱用法" id="基础沙箱用法"> 沙箱预设已包含默认的本地/私网屏蔽与文件系统隔离。以下示例展示如何在预设基础上叠加自定义配置。 ```bash title="启用沙箱（使用预设配置）" arcadia run example.js --sandbox ``` ```bash title="在预设基础上完全断网" arcadia run example.js --sandbox --sandbox-net-deny-all ``` ```bash title="显式声明屏蔽局域网与云元数据" arcadia run example.js --sandbox --sandbox-net-deny-local ``` ```bash title="组合使用：内存限制 + 环境变量隔离" arcadia run example.js \ --sandbox \ --sandbox-max-memory 256M \ --sandbox-clear-env \ --sandbox-env NOTIFY_KEY=xxx \ --sandbox-env TZ=Asia/Shanghai ``` ```bash title="运行不可信脚本：完全断网 + 内存限制 + 清空环境变量" arcadia run untrusted.js \ --sandbox \ --sandbox-net-deny-all \ --sandbox-max-memory 256M \ --sandbox-clear-env ``` 注意：`--sandbox` 预设默认禁止访问本机与内网地址，公网访问正常；需要完全断网时必须显式指定 `--sandbox-net-deny-all`。 </Accordion> <Accordion title="网络出站控制" id="网络出站控制"> 预设默认禁止访问本机与内网地址，公网出站连接正常放行。以下选项用于进一步调整： * **白名单**（`--sandbox-net-allow`）：指定后取代默认网络预设，仅放行匹配的连接。 * **黑名单**（`--sandbox-net-deny` / `--sandbox-net-deny-local`）：在默认屏蔽本地的基础上追加屏蔽匹配的连接，二者可叠加。 * **完全断网**（`--sandbox-net-deny-all`）：与其余出站控制及 HTTP 过滤选项互斥，端口绑定不受影响。 ```bash title="白名单：仅允许访问指定 API 和 DNS" arcadia run example.js \ --sandbox \ --sandbox-net-allow tcp://api.openai.com:443 \ --sandbox-net-allow udp://1.1.1.1:53 ``` ```bash title="黑名单：在默认本地屏蔽基础上追加自定义网段" arcadia run example.js \ --sandbox \ --sandbox-net-deny 198.51.100.0/24 ``` ```bash title="Agent 场景：仅允许访问指定 API，并收紧环境变量" arcadia run agent.js \ --sandbox \ --sandbox-net-allow tcp://api.openai.com:443 \ --sandbox-http-allow "POST api.openai.com/v1/*" \ --sandbox-allow-env-whitelist PATH,HOME \ --sandbox-env OPENAI_API_KEY=xxx ``` <Callout type="info" title="规则语法"> 规则支持以下格式： | 格式 | 含义 | | --------------------------- | ---------------------------------------- | | `api.example.com:443` | 指定主机 + 端口（不带协议前缀 scheme 时同时覆盖 TCP 和 UDP） | | `api.example.com:80,443` | 同一主机的多个端口 | | `tcp://api.example.com:443` | 仅 TCP | | `udp://1.1.1.1:53` | 仅 UDP（如 DNS 查询） | | `udp://*:*` / `tcp://*:*` | 任意目标的指定协议、所有端口 | | `10.0.0.0/8` | CIDR 网段 | | `169.254.169.254` | 单个 IP | | `[2606:4700::/32]:443` | IPv6 网段 + 端口 | | `1.1.1.1:*` | 指定主机的所有端口 | | `:8443` | 指定任意主机的特定端口 | | `*` / `*:*` | 任意出站连接（二者等价） | | `icmp://*` | ICMP（如 ping，仅 `--sandbox-net-allow`） | 注意：主机名仅 `--sandbox-net-allow` 支持（启动时解析并锁定）；`--sandbox-net-deny` 仅接受 IP/CIDR（可带端口与协议前缀），不支持主机名。 可以查看官方文档的使用示例 [《Network Policy》](https://sandlock.io/docs/network) </Callout> </Accordion> <Accordion title="HTTP 请求过滤" id="HTTP请求过滤"> 在预设网络或自定义网络控制的基础上，可进一步按 HTTP 方法和路径过滤请求。 ```bash title="白名单：仅允许 GET 文档站和 POST API" arcadia run example.js \ --sandbox \ --sandbox-http-allow "GET docs.python.org/*" \ --sandbox-http-allow "POST api.openai.com/v1/*" ``` ```bash title="黑名单：屏蔽所有对 /admin 路径的请求" arcadia run example.js \ --sandbox \ --sandbox-http-deny "* */admin/*" ``` <Callout type="info" title="规则格式"> 每条规则格式为 `"METHOD host/path"`（需用引号包裹，因为含空格）： * `METHOD`：HTTP 方法（如 `GET`、`POST`，`*` 表示任意方法，不区分大小写） * `host/path`：目标主机 + 路径模式（`*` 为通配符） `--sandbox-http-allow` 与 `--sandbox-http-deny` 互斥，不可同时使用。 可以查看官方文档的使用示例 [《HTTP ACL and Credential Injection》](https://sandlock.io/docs/http-acl) </Callout> 使用 HTTPS 过滤时默认不需要配置证书，Arcadia CLI 会根据运行文件的语言环境自动配置；需要自定义证书加载方式时，请参考下方对应语言和请求库的示例。 <Tabs defaultValue="python"> <TabsList> <TabsTrigger value="python"> Python </TabsTrigger> <TabsTrigger value="javascript"> JavaScript / TypeScript </TabsTrigger> <TabsTrigger value="go"> Go </TabsTrigger> <TabsTrigger value="rust"> Rust </TabsTrigger> <TabsTrigger value="ruby"> Ruby </TabsTrigger> <TabsTrigger value="other"> 其他 </TabsTrigger> </TabsList> <TabsContent id="http-cert-python" value="python"> <Tabs defaultValue="requests"> <TabsList> <TabsTrigger value="requests"> requests </TabsTrigger> <TabsTrigger value="ssl-cert-file"> httpx / urllib </TabsTrigger> </TabsList> <TabsContent id="http-cert-python-requests" value="requests"> `requests` 通过 `REQUESTS_CA_BUNDLE` 加载： ```bash arcadia run example.py --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env REQUESTS_CA_BUNDLE=/tmp/sandlock-ca.pem ``` </TabsContent> <TabsContent id="http-cert-python-ssl" value="ssl-cert-file"> `httpx` 和标准库 `urllib` 都通过 `SSL_CERT_FILE` 加载： ```bash arcadia run example.py --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env SSL_CERT_FILE=/tmp/sandlock-ca.pem ``` </TabsContent> </Tabs> </TabsContent> <TabsContent id="http-cert-javascript" value="javascript"> <Tabs defaultValue="node-bun"> <TabsList> <TabsTrigger value="node-bun"> Node / Bun </TabsTrigger> <TabsTrigger value="deno"> Deno </TabsTrigger> </TabsList> <TabsContent id="http-cert-javascript-node-bun" value="node-bun"> node / tsx / ts-node / Bun 都通过 `NODE_EXTRA_CA_CERTS` 加载。CLI 已自动设置，以下写法适用于自定义 `--http-ca-out` 路径或打包产物： ```bash arcadia run example.js --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env NODE_EXTRA_CA_CERTS=/tmp/sandlock-ca.pem ``` </TabsContent> <TabsContent id="http-cert-javascript-deno" value="deno"> Deno 通过 `DENO_CERT` 加载。CLI 已自动设置，以下写法适用于自定义 `--http-ca-out` 路径： ```bash arcadia run example.ts --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env DENO_CERT=/tmp/sandlock-ca.pem ``` </TabsContent> </Tabs> </TabsContent> <TabsContent id="http-cert-go" value="go"> Go 的 `net/http` 通过 `SSL_CERT_FILE` 加载： ```bash arcadia run example.go --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env SSL_CERT_FILE=/tmp/sandlock-ca.pem ``` </TabsContent> <TabsContent id="http-cert-rust" value="rust"> reqwest 默认（native-tls / rustls-native-certs）通过 `SSL_CERT_FILE` 加载： ```bash arcadia run example.rs --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env SSL_CERT_FILE=/tmp/sandlock-ca.pem ``` 如果依赖 `webpki-roots` 或 `rustls-platform-verifier` 这类自带/平台证书校验的库，环境变量不生效，需在代码中显式加载： ```rust let pem = std::fs::read("/tmp/sandlock-ca.pem")?; let cert = reqwest::Certificate::from_pem(&pem)?; let client = reqwest::Client::builder() .add_root_certificate(cert) .build()?; ``` </TabsContent> <TabsContent id="http-cert-ruby" value="ruby"> <Tabs defaultValue="openssl"> <TabsList> <TabsTrigger value="openssl"> net/http / rest-client / httparty </TabsTrigger> </TabsList> <TabsContent id="http-cert-ruby-openssl" value="openssl"> `net/http`、`rest-client`、`httparty` 底层都基于 OpenSSL，通过 `SSL_CERT_FILE` 加载： ```bash arcadia run example.rb --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env SSL_CERT_FILE=/tmp/sandlock-ca.pem ``` </TabsContent> </Tabs> </TabsContent> <TabsContent id="http-cert-other" value="other"> <Tabs defaultValue="openssl"> <TabsList> <TabsTrigger value="openssl"> Lua / Perl </TabsTrigger> <TabsTrigger value="curl"> curl </TabsTrigger> </TabsList> <TabsContent id="http-cert-other-openssl" value="openssl"> Lua `luasec` 和 Perl `LWP` 都基于 OpenSSL，通过 `SSL_CERT_FILE` 加载： ```bash arcadia run example.lua --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env SSL_CERT_FILE=/tmp/sandlock-ca.pem ``` </TabsContent> <TabsContent id="http-cert-other-curl" value="curl"> Shell 脚本中的 curl 可通过 `CURL_CA_BUNDLE` 或 `--cacert` 加载： ```bash arcadia run example.sh --sandbox \ --sandbox-http-allow "GET api.example.com/*" \ --sandbox-opts "--http-ca-out /tmp/sandlock-ca.pem" \ --sandbox-env CURL_CA_BUNDLE=/tmp/sandlock-ca.pem ``` ```bash title="example.sh" curl --cacert /tmp/sandlock-ca.pem https://api.example.com ``` </TabsContent> </Tabs> </TabsContent> </Tabs> </Accordion> <Accordion title="端口绑定（服务端监听）" id="端口绑定"> 预设禁止绑定监听任何端口。如果代码文件需要作为服务端运行，需显式放行： ```bash title="允许绑定指定端口" arcadia run server.js \ --sandbox \ --sandbox-net-allow-bind 8080,9000-9005 ``` ```bash title="允许绑定任意端口" arcadia run server.js \ --sandbox \ --sandbox-net-allow-bind-all ``` 端口绑定控制与出站网络控制完全独立，互不干涉。 </Accordion> <Accordion title="文件系统访问" id="文件系统访问"> 沙箱预设已挂载代码文件（脚本）运行所需的基本目录。如需额外访问其它路径： ```bash title="追加只读 + 读写目录" arcadia run example.js \ --sandbox \ --sandbox-allow-read /tmp/data \ --sandbox-allow-write /tmp/output ``` `--sandbox-allow-read` 授予只读权限，`--sandbox-allow-write` 授予读写权限，均可多次使用。 </Accordion> <Accordion title="环境变量控制" id="环境变量控制"> 预设继承全部环境变量。以下选项用于收紧或定制： ```bash title="白名单模式：仅保留 PATH 和 HOME" arcadia run example.js \ --sandbox \ --sandbox-allow-env-whitelist PATH,HOME ``` ```bash title="黑名单模式：排除敏感变量" arcadia run example.js \ --sandbox \ --sandbox-allow-env-blacklist SECRET_KEY,PRIVATE_TOKEN ``` 逻辑关系： * `--sandbox-clear-env` 与 `--sandbox-allow-env-whitelist` 互斥（后者已隐式启用清空）。 * `--sandbox-env` 始终在清空/过滤之后追加，可与任意选项组合。 * `--sandbox-allow-env-blacklist` 与 `--sandbox-clear-env`、`--sandbox-allow-env-whitelist` 互斥。 </Accordion> <Accordion title="关于透传底层参数" id="透传底层参数"> 用于传递上述选项未覆盖的 sandlock 底层参数。选项名与值写在同一字符串内，可多次使用。 ```bash title="透传未覆盖的底层参数（自定义 CA 注入）" arcadia run example.js \ --sandbox \ --sandbox-opts "--http-allow 'GET example.com/*' --http-inject-ca /etc/ssl/certs/custom-ca.pem" ``` <Callout type="warn" title="注意"> 透传参数中含空格、引号、通配符、方括号等特殊字符时，必须用引号包裹。请勿与高层选项重复传递同一参数（例如已使用 `--sandbox-http-allow` 时，不要再通过 opts 传 `--http-allow`），否则会抛出错误。 </Callout> </Accordion> </Accordions> ### 更新沙箱引擎 [#更新沙箱引擎] Arcadia CLI 会在首次使用沙箱功能时自动下载并安装 Sandlock，但不会自动检查新版本。如若首次下载失败，可尝试使用该命令进行安装。 <CodeBlockTabs defaultValue="GitHub"> <CodeBlockTabsList> <CodeBlockTabsTrigger value="GitHub"> GitHub </CodeBlockTabsTrigger> <CodeBlockTabsTrigger value="GitHub Proxy 代理"> GitHub Proxy 代理 </CodeBlockTabsTrigger> </CodeBlockTabsList> <CodeBlockTab value="GitHub"> ```bash download_url="https://github.com/multikernel/sandlock/releases/latest/download/sandlock-$(arch)-unknown-linux-gnu.tar.gz" query_url="https://api.github.com/repos/multikernel/sandlock/releases/latest" target_dir="${ARCADIA_DIR}/src/shell/sandbox" sandlock_path="${target_dir}/sandlock" [ -x "${sandlock_path}" ] && current_version="$(${sandlock_path} --version | awk -F ' ' '{print$NF}')" || current_version="" [[ -x "${sandlock_path}" && "$(curl -s "${query_url}" | jq -r ".tag_name" | sed 's|^v||g')" == "${current_version}" ]] && echo "Sandlock 已是最新版本 ${current_version}" || { git -C "${target_dir}" ls-files --others --exclude-standard -z | tr '\0' '\n' | sed "s|^|${target_dir}/|" | tr '\n' ' ' | xargs -r rm -f wget -q --show-progress -O - "${download_url}" | tar -xzf - -C "${target_dir}" chmod a+x "${target_dir}/sandlock" echo "Sandlock 已安装" } ``` </CodeBlockTab> <CodeBlockTab value="GitHub Proxy 代理"> ```bash download_url="https://ghfast.top/https://github.com/multikernel/sandlock/releases/latest/download/sandlock-$(arch)-unknown-linux-gnu.tar.gz" query_url="https://api.github.com/repos/multikernel/sandlock/releases/latest" target_dir="${ARCADIA_DIR}/src/shell/sandbox" sandlock_path="${target_dir}/sandlock" [ -x "${sandlock_path}" ] && current_version="$(${sandlock_path} --version | awk -F ' ' '{print$NF}')" || current_version="" [[ -x "${sandlock_path}" && "$(curl -s "${query_url}" | jq -r ".tag_name" | sed 's|^v||g')" == "${current_version}" ]] && echo "Sandlock 已是最新版本 ${current_version}" || { git -C "${target_dir}" ls-files --others --exclude-standard -z | tr '\0' '\n' | sed "s|^|${target_dir}/|" | tr '\n' ' ' | xargs -r rm -f wget -q --show-progress -O - "${download_url}" | tar -xzf - -C "${target_dir}" chmod a+x "${target_dir}/sandlock" echo "Sandlock 已安装" } ``` </CodeBlockTab> </CodeBlockTabs> 若频繁使用沙箱功能，建议定期手动更新，后续可能会调整安装策略。 # 终止运行 ```bash title="终止运行中的代码程序（脚本）" arcadia stop <name/path> ``` 终止某个或某些正在运行中的代码程序，根据代码文件名称搜索对应的进程并立即杀死，支持终止多进程任务例如并发任务。 `<name>` 文件名(仅scripts目录) `<path>` 相对路径或绝对路径 <Callout type="info" icon="false"> 该命令仅能有效终止由 `arcadia run` 命令启动的代码程序，无法终止由其它方式启动的代码程序。 </Callout>