# 关于我们 ## 社区 [#社区] 加入我们位于 logos:telegram Telegram 的 [官方频道](https://t.me/ArcadiaPanel) 和 [交流群组](https://t.me/ArcadiaPanelGroup) ## Issue 反馈 [#issue-反馈] 请前往 [GitHub 仓库](https://github.com/SuperManito/Arcadia/issues) 提交您的问题。我们不接受任何使用问题，这只会让你创建的 issue 被立即关闭，如果你需要获取帮助请加入社区后与社区成员进行交流。 ㅤ ## 开发者 [#开发者] ## 支持我们 [#支持我们] 成为赞助商享有文档广告展示，如有需求请在社区中主动联系作者，更多内容有待完善。 # 更新日志 ## `1.0.0-beta.11 (2026-06-03)` [#100-beta11-2026-06-03] ### ✨ 新特性 \[!toc] [#-新特性-toc] * 控制面板 * 新增《环境配置 - 依赖管理》页面 * 新增运行代码文件命令可视化组件 * 全新的文件移动组件 * 《文件管理》页新增快捷操作导航栏 * 《个人设置》页新增系统时区配置 * 新增部分代码高亮主题 * 大量UI设计与动效更新 * 代码同步 * 代码文件配置新增指定文件名称配置项 ### 🛠️ 优化 \[!toc] [#️-优化-toc] * 前端：优化了部分页面和组件的行为逻辑 * 后端：更换了图形验证码生成引擎并大幅提高防护强度 * 更新 TypeScript 至 V6 版本 ## `1.0.0-beta.10 (2026-04-08)` [#100-beta10-2026-04-08] ### ✨ 新特性 \[!toc] [#-新特性-toc-1] * 控制面板 * 新增《守护任务》页面，支持管理守护进程任务 * 《定时任务 - 任务配置》页支持查看运行中任务的实时输出（日志） * 大量UI设计更新 * CLI * 运行代码文件：新增 rund 子命令，移除守护运行命令选项 ### 🛠️ 优化 \[!toc] [#️-优化-toc-1] * 前端：终端现在强制深色主题 ### 🐛 修复 \[!toc] [#-修复-toc] * 前端：修复了在登录后未能触发上次登录提醒的问题 ## `1.0.0-beta.9 (2026-03-26)` [#100-beta9-2026-03-26] ### ✨ 新特性 \[!toc] [#-新特性-toc-2] * 控制面板 * 新增基于 Ghostty 的模拟终端，支持移动端操作 * 《环境配置 - 环境变量》页新增支持标签分类过滤，去除了标签颜色设计 * 《个人设置》页新增 “系统日志” 分页，支持查看操作日志和登录日志 * 《个人设置》页新增 “命令行” 分页，用于配置 Arcadia CLI 功能 * 《个人设置 - 令牌管理》页权限控制改为更详细的权限控制列表 * 《代码编辑》页文件树右键菜单新增 “在终端中打开” 与 “安装依赖” 功能 * 支持查看图片文件 * 后端服务 * 加强 OpenAPI 接口权限管理，改为细粒度分类控制 * 新增 “Exec 命令执行” 系列 OpenAPI 接口，支持 SSE 流式传输 * CLI * 运行代码文件：新增 Python 脚本 uv 工具集成 * 运行代码文件：新增指定 JavaScript 和 TypeScript 脚本的默认运行时配置 ### 🛠️ 优化 \[!toc] [#️-优化-toc-2] * 前端：《代码编辑》页调试运行默认不再自动保存文件内容 * 前端：《代码编辑》与《日志查询》页的文件树改为异步加载 * 前端：改善了《代码编辑》页的部分操作行为逻辑 ### 🐛 修复 \[!toc] [#-修复-toc-1] * 前端：修复了作为独立应用模式使用时未能正确同步 iOS 状态栏颜色的问题 * 后端：修复定时任务部分高级配置无效的问题 * CLI：修复在使用 “不记录日志命令” 命令选项时仍创建日志目录的问题 ## `1.0.0-beta.8 (2026-03-02)` [#100-beta8-2026-03-02] ### ✨ 新特性 \[!toc] [#-新特性-toc-3] * 前端：“个人设置 - 令牌管理” 页面新增访问权限控制，可以为指定令牌单独设置接口访问权限 * 前端：“个人设置 - 身份认证” 页面新增登出所有设备功能 ### 🐛 修复 \[!toc] [#-修复-toc-2] * 前端：修复 JS 类文件代码高亮失效的问题 * 前端：修复 “代码同步” 页面部分配置字段关联文档链接无效的问题 * CLI：修复在更新指定名称的代码同步配置时未能导入定时任务的问题 ## `1.0.0-beta.7 (2026-02-23)` [#100-beta7-2026-02-23] ### ✨ 新特性 \[!toc] [#-新特性-toc-4] * 前端：新增 “定时任务仪表盘” 页面，实现可视化浏览定时任务运行数据 * 前端：新增 “代码同步” 页面，实现可视化管理代码文件导入配置 * 前端：移除 “代码调试” 页面，其功能已合并至 “代码编辑” 页面 * 前端：“代码对比” 页面新增差异计算状态消息，以改善用户体验 * 前端：“个人设置” 身份认证页面新增双重认证配置功能 * 前端：“个人设置” 新增令牌管理分页，支持管理 OpenAPI 令牌 * 前端：“文件管理” 页面新增框选和拖拽功能，提供类似视窗文件管理器的交互体验 * 前端：“文件管理” 页面新增支持文件预览 * 前端：“文件管理” 页面批量操作新增移动端适配和下载操作 * 前端：新增适配更多文件类型图标与代码高亮 * 前端：为部分UI界面和组件添加了记忆用户选择功能 * 前端：为日志相关组件更换了新的等宽字体 * 前端：大量UI设计与动效更新 * 后端：新增项目配置系列API，用于存储项目配置 * 后端：重构登录认证架构，新增 2FA 双重认证 * 后端：重构文件目录结构与数据库封装 * 后端：强化了认证架构与文件系统整体安全性 * CLI：运行代码文件命令新增 “指定并发线程数” 命令选项 * CLI：运行代码文件命令新增 “执行参数” 命令选项 * CLI：运行代码文件命令新增 “传递选项” 命令选项 * CLI：终止代码文件命令支持终止多任务进程 * CLI：更新代码同步命令新增 “更新指定配置” 子命令 * CLI：添加代码同步配置命令完善相关命令选项 ### 🐛 修复 \[!toc] [#-修复-toc-3] * 前端：修复 “定时任务” 页面查看源码组件未按预期保存文件内容的错误 * CLI：修复代码同步配置禁用无效的问题 ### 🛠️ 优化 \[!toc] [#️-优化-toc-3] * 前端：大幅缩减前端打包体积并提高了页面加载速度 ## `1.0.0-beta.6 (2025-04-28)` [#100-beta6-2025-04-28] ### ✨ 新特性 \[!toc] [#-新特性-toc-5] * 前端：重新设计了 “定时任务” 页面查看源码组件，现在支持直接编辑 * 前端：代码编辑器工具箱新增支持语言模型选择器、内容替换按钮 * 前端：“代码对比” 页面新增差异跳转、对比互换等功能 * 前端：运行命令组件添加调整字体大小按钮 * 前端：新增 socket 连接异常弹窗提示组件，支持手动重连 * 前端：大量UI细节与动效更新 * 后端：使用 TypeScript 重构 * CLI：新增适配 Deno 和 tsx 运行环境 ### 🛠️ 优化 \[!toc] [#️-优化-toc-4] * 前端：改善了代码编辑器标签页多开功能，现在能够恢复关闭时的编辑状态 * 前端：改善了移动端编辑器键盘控制悬浮组件的展示机制与位置 * 前端：优化了代码编辑器部分功能的逻辑 * 前端：图标全量本地化，现在前端支持网络离线环境下使用 * 前端：定时任务页面 “用户” 类型更名为 “个人” * 前端：“对比工具” 页面重命名为 “代码对比” * 前端：强化移动端适配，改善交互体验 * CLI：优化了部分命令的传参路径处理，现在能更好的处理 `.` `..` `./` 等路径符号 * CLI：使用 tsx 替代 ts-node 作为默认的 TypeScript 代码文件执行器 ### 🐛 修复 \[!toc] [#-修复-toc-4] * 前端：修复了代码编辑器的一些显示错误 * CLI：修复了一些错误 ## `1.0.0-beta.5 (2024-10-16)` [#100-beta5-2024-10-16] ### ✨ 新特性 \[!toc] [#-新特性-toc-6] * 前端：“定时任务” 页面支持卡片视图 * 前端：“定时任务” 页面新增查看详情组件 * 前端：“环境变量” 与 “定时任务” 页面支持搜索内容高亮 * 前端：“代码编辑” 页面支持批量删除 * 后端：新增封装 “文件系统” 系列 OpenAPI 接口，具体详见开发者文档 * CLI：新增适配 Bun、Lua、Ruby、Rust、Perl 运行环境，前端同步适配 ### 🛠️ 优化 \[!toc] [#️-优化-toc-5] * 前端：改善了一些功能针对特定场景的工作逻辑 * 前端：改善了 “文件管理” 页面列表视图的布局 * 前端：改善了代码编辑器在移动端的使用体验 * 前端：为部分弹窗功能适配了回车确认 * 后端：重新设计了整个文件系统，调整了接口的路径、传参以及响应参数 ### 🐛 修复 \[!toc] [#-修复-toc-5] * 后端：修复了一些错误 ## `1.0.0-beta.4 (2024-09-14)` [#100-beta4-2024-09-14] ### ✨ 新特性 \[!toc] [#-新特性-toc-7] * 前端：更新了整体框架布局和大量页面以及组件的 UI 设计 * 前端：代码编辑器工具箱新增封装多个功能操作 * 前端：“定时任务” 页面编辑任务组件新增定时高级配置 * 前端：“运行日志” 页面支持轮询更新 * 前端：“运行日志” 页面支持日志反转 * 前端：“文件管理” 页面支持批量操作 * 前端：代码编辑器新增部分深色主题 * 后端：新增封装 “定时任务” 系列 OpenAPI 接口，具体详见开发者文档 * 后端：新增 “环境变量” OpenAPI 精准查询接口 * 后端：为 “环境变量” OpenAPI 查询接口添加了描述与备注字段的匹配 ### 🐛 修复 \[!toc] [#-修复-toc-6] * 后端：修复了在更新项目源码后，后端服务不符合预期自动重启的错误 * 后端：修复了一些错误 ### 🛠️ 优化 \[!toc] [#️-优化-toc-6] * 前端：提高了代码编辑器的渲染性能 * 前端：优化了静态资源的打包体积，提高了页面加载速度 * 前端：表格分页大小的用户设置支持本地存储 * 后端：优化了终止定时任务的实现逻辑 * 后端：为最近登录地理位置信息添加了局域网识别 * 后端：完善了接口响应机制 * 后端：优化了部分接口的处理逻辑，提高了性能 * CLI：调整了运行代码存储日志文件的路径 ## `1.0.0-beta.3 (2024-05-07)` [#100-beta3-2024-05-07] ### ✨ 新特性 \[!toc] [#-新特性-toc-8] * 前端：“环境变量” 复合变量值分页表格新增批量导入组件 * 前端：“环境变量” 页面表格新增更新时间字段 * 前端：UI细节更新 ## `1.0.0-beta.2 (2024-05-05)` [#100-beta2-2024-05-05] ### ✨ 新特性 \[!toc] [#-新特性-toc-9] * 后端：新增封装 “环境变量” 系列 OpenAPI 接口，具体详见开发者文档 ### 🐛 修复 \[!toc] [#-修复-toc-7] * 后端：修复了在添加新的系统定时任务后导致所有原有任务被自动删除的错误 * 后端：修复了被禁用的普通变量仍被导出的错误 * CLI：修复了一些命令的兼容性错误 * CLI：修复了一些命令选项的错误 ### 🛠️ 优化 \[!toc] [#️-优化-toc-7] * 后端：优化了批量管理系统定时任务接口的性能，提高了底层定时导入速度 ## `1.0.0-beta.1 (2024-04-28)` [#100-beta1-2024-04-28] ### ✨ 新特性 \[!toc] [#-新特性-toc-10] * 前端：新增 “环境变量” 页面，可通过表格和表单来管理用户变量数据 * 前端：全面应用了基于 TextMate 的代码语法高亮引擎，现在代码编辑器不仅更加美观还大幅提高了渲染速度，并且对于长文本解析有着出色的性能表现。 * 前端：原 “脚本管理” 页面重命名为 “文件编辑”，原 “脚本调试” 页面重命名为 “代码调试” * 前端：重新设计了 “运行日志” 和 “文件编辑” 页面的折叠侧边栏的UI交互 * 前端：“个人设置” 页面个性化分页新增自定义代码高亮主题样式配置 * 前端：“定时任务” 页面表格数据项操作列新增支持主动运行和终止运行功能 * 前端：“定时任务” 页面表格新增支持列排序，并且适配了数据项的调整排序功能 * 前端：为表格组件添加了导出数据按钮，并更新了列设置UI设计 * 前端：更新了多个页面和组件的动画效果，提升了用户体验 * 前端：为部分弹窗组件添加了全屏展示按钮 * 前端：大量UI设计更新 * 后端：重构了数据库操作封装，现在使用基于 Prisma 的 ORM 框架 * 后端：新增封装环境变量相关功能接口 * CLI：底层Shell完全重构，重新设计了项目指令，新增部分命令选项 * CLI：新增支持运行 Go 语言和 C 语言的代码文件 ### 🐛 修复 \[!toc] [#-修复-toc-8] * 前端：修复了运行日志通用组件位于标题栏的运行计时显示错误 * 前端：修复了在部分情况下编辑器需要刷新页面才能正常显示的问题 * 前端：修复了 “文件管理” 页面当文件（夹）名称过长时不符合预期的显示错误 ### 🛠️ 优化 \[!toc] [#️-优化-toc-8] * 前端：大幅提高了 “运行日志” 和 “文件编辑” 页面在移动端上的性能表现 * 前端：改进了多个页面的运行效率，优化了内存占用。 * 前端：调整了菜单选项的路由配置，现在支持右键操作 * 前端：优化了部分页面文件选择组件的交互，现在会正确处理目录节点的点击行为且不再被禁用 * 前端：优化了 “个人设置” 页面的布局 * 前端：当使用移动端书签应用时顶部系统导航栏的背景颜色现在会与主题同步 * 前端：现在编辑器组件全局默认自动换行 * 后端：代码完全重构，并配置 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) 是 CLI 运行 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 它的兼容性会更高，不过性能会差很多。 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 平台主要面向于脚本语言编程与运维，支持定时任务调度，有着完善的文件系统和底层CLI命令设计，适用于中小型团队与个人的开发与运维环境。本项目基于 TypeScript 全栈开发，采用了众多前沿技术，前端使用 Vue + Vite，后端使用 Node.js + Express + Prisma ORM。文档分为4个部分：使用文档命令行文档应用程序接口文档开放应用程序接口文档 ## 名字的由来 [#名字的由来] **Arcadia** 源自希腊语 *Αρκαδία*，中文译名为 *阿卡迪亚*，它是希腊的一个二级行政区（州），位于伯罗奔尼撒半岛的中部山区，现被西方广泛引申为乌托邦，是传说中世界的中心位置，相当于中华文化中的世外桃源。 ## 支持哪些编程语言 [#支持哪些编程语言] 已适配可直接运行代码文件的语言环境如下 | 类型 | 文件格式 | | :--------: | :-----------------: | | 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) ## 已在规划中的新内容 [#已在规划中的新内容] 在这里我们会预告一些即将到来尚未开发完毕的新功能 * 下一阶段 * 消息中心 * 监控告警 * 未来开发计划 * 代码片段 * API测试 * 命令行移动端操作适配 * 流程编排（工作流） # 推送通知即将上线消息中心和监控告警功能，当前内容将被废弃已不再维护，注意持续关注项目的功能变动用于在运行脚本后将指定内容推送到你的设备上，推送内容由脚本而定，可同时使用多个渠道的推送通知服务\ 目前提供：Server酱、Bark、Telegram、钉钉、企业微信、iGot、pushplus、go-cqhttp、WxPusher 此功能基于底层 `sendNotify.js` 脚本实现编辑配置 - 下拉选择 `config.sh` - 推送通知设置区域 * ### 通知尾 [#通知尾] ```bash export NOTIFY_TAIL="本通知 By：https://github.com/SuperManito/Arcadia" ``` 默认如上，如想修改请编辑 **config.sh** 配置文件中的变量 * ### 通知屏蔽 [#通知屏蔽] ```bash export NOTIFY_MASKING="" ``` 变量中填写想要屏蔽的关键词，多个词用 `&` 连接，注意屏蔽针对的是内容而不是通知标题 *** ## Server酱 [#server酱] 官网：[https://sct.ftqq.com](https://sct.ftqq.com) * SCHKEY 或 SendKey（必填） ```bash export PUSH_KEY="" ``` * 自建 Server 酱（选填） ```bash export SCKEY_WECOM="" export SCKEY_WECOM_URL="" ``` *** ## Bark [#bark] * 设备码（必填） ```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 [#telegram] 注意网络连通性问题，可能需要魔法 * 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` *** ## 钉钉 [#钉钉] 官方文档：[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** 等字符钉钉机器人安全设置只需勾选加签即可，其他选项不要勾选 *** ## 企业微信机器人 [#企业微信机器人] 官方文档：[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` *** ## 企业微信应用 [#企业微信应用] 参考文档：[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聚合 [#igot聚合] 官方文档：[https://wahao.github.io/Bark-MP-helper](https://wahao.github.io/Bark-MP-helper) * 推送key（必填） ```bash export IGOT_PUSH_KEY="" ``` 支持多方式推送，确保消息可达 *** ## pushplus [#pushplus] 官网：[http://www.pushplus.plus](http://www.pushplus.plus) * Token（必填） ```bash export PUSH_PLUS_TOKEN="" ``` 微信扫码登录后一对一推送或一对多推送下面的 token，只填此变量默认为一对一推送 * 一对一多推送群组编码（选填） ```bash export PUSH_PLUS_USER="" ``` 一对多推送下面 -你的群组(如无则新建) -群组编码需订阅者扫描二维码；如果你是创建群组所属人，也需点击 **查看二维码** 扫描绑定 *** ## WxPusher [#wxpusher] 官方仓库：[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="" ``` *** 此页文档如有描述错误或其它问题请积极向开发者进行反馈，谢谢 # 控制面板默认通过 `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 浏览器，访问控制面板登录页面并点击分享按钮，选择“添加到主屏幕”，之后在桌面打开即可像原生应用一样快速访问控制面板。 ## 常见问题 [#常见问题] 在不重新部署的情况下更改面板映射端口请在宿主机执行下面的命令 * 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. 如果你正在使用旁路由则可能需要将网络模式切换为 **host** 类型，点击 “高级配置” 将网络模式设置为 `host` 4. 不可以更改参数中 `:` 右边的内容，否则会导致后端服务无法正常访问 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 芯片容器挂载目录的作用是将宿主机的文件系统目录或文件挂载到容器内部。挂载后，容器内的程序可以像访问本地文件一样访问这些文件或目录，同时宿主机上的应用也可直接对其进行操作。这种机制实现了容器与宿主机之间的文件共享，使得数据持久化成为可能——即使容器被删除，挂载的数据仍保留在宿主机上，便于后续迁移或复用。当前底层镜像基于 `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) 设计紧密相连，具体详见 [运行代码文件（脚本）](/docs/cli/script/run) 定时任务功能是 Arcadia 平台的核心功能之一，定时任务会运行任务配置中的 Shell 命令，不强制关联代码文件。其中系统类型的任务由[代码同步](/docs/sync)功能自动管理，你可以通过代码同步功能中的定时任务配置来实现自动导入定时任务。具体请详见[代码同步](/docs/sync)文档，代码同步功能是 Arcadia 平台用于导入代码（文件）的统称，目前支持 “代码仓库” 与 “代码文件” 两种类型并提供丰富的功能性配置。如果你想 **自动更新** 代码同步功能中订阅的脚本，请在控制面板《定时任务》页面创建 `arcadia update` 个人任务详见 CLI 文档 [清理日志](/docs/cli/sundry/rmlog)

# 更新升级正式版的版本号格式为 `x.xx.xx`，其中第一位为主版本号，第二位为次版本号，第三位为修订版本号，更新修订版本无需重新部署直接更新项目源码即可，次版本根据更新日志的要求而定；如果你使用的是测试版本那么需要持续保持镜像容器至最新

自动更新镜像容器工具

使用 [watchtower](https://github.com/containrrr/watchtower) 自动更新镜像容器 ``` docker run -d \ --name watchtower \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower -c \ --schedule "0 0 */2 * * *" ``` 最下边的 Cron 表达式是更新频率（秒、分、时、日、月、周），可自行定义该工具容器会自动更新正在使用的镜像并在更新后自动重启相关容器

如果你想了解的是如何更新导入的代码文件，那么请前往查看 [CLI 文档](/docs/cli/update/upgrade) ## 更新源码 [#更新源码] 小版本升级直接更新源码即可 ```bash title="更新源代码" arcadia upgrade ``` 如果你的网络环境不能有效连通 GitHub，那么则需要使用代理，下面提供一个简单且免费的方法

使用免费代理进行更新

```bash title="将项目官方远程仓库地址替换为开源代理地址" cd /arcadia/src git remote set-url origin https://ghfast.top/https://github.com/SuperManito/Arcadia.git cd /arcadia ``` 之后就可以正常使用 `arcadia upgrade` 了

## 更新容器 [#更新容器] * #### 一键更新 [#一键更新] ```bash docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower -c --run-once arcadia ``` 可以通过此命令一键更新，不过需要注意的是更新镜像容器会删除已安装的环境例如 npm 依赖包等，需要重新安装 * #### 重新部署 [#重新部署] 根据通知要求而定，如果你想重新安装那么需要先删除运行中的容器和镜像 ```bash docker rm -f arcadia docker rmi arcadia ``` 前往查看[安装文档](/docs/quick-start) 如果你有在控制面板《环境配置 - 依赖管理》配置全局依赖，那么可以使用该页面提供的 ”一键安装“ 功能自动补全环境。 # 概述 ## 基础 [#基础] 核心入口指令为 `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 "<命令>"`，多个命令需用 `;` 或 `&&` 连接即 `"<命令> && <命令>"` 后者 `&&` 表示前一条命令执行成功时再执行后一条命令，否则遇到报错会中断，相比前者用法较为特殊 # 概述 ## 接口基准地址 [#接口基准地址] `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` | 请求成功 | ## 参数传递 [#参数传递] 除 GET 请求通过 URL 传递参数外，其它请求方式均通过 Body 传递参数 ## WebSocket 接口 [#websocket-接口] 基准地址 * `ws://localhost:5678` 鉴权方式与 HTTP 接口相同目前有两个业务 * `/api/ws` 实时数据推送 * `/api/terminal` 终端服务 ## 接口类别 [#接口类别] # 概述可下载并导入到 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 ```

## 接口类别 [#接口类别] # 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": "<你的密码>", } ``` # 代码同步代码同步是 Arcadia 平台用于导入代码（文件）的功能统称，核心配置文件为 `/arcadia/config/sync.yaml`，建议通过控制面板《环境配置 - 代码同步》页面进行可视化编辑与使用，本部分文档主要介绍配置方法与各字段含义 > 如果你想导入本地代码文件那么直接上传至 `/arcadia/scripts` 目录下即可 ## 关于定时任务 [#关于定时任务] 对于定时任务功能平台有专门的前端管理页面，可进行可视化操作，目前设计了两个功能板块（标签页）一个是基于 `sync.yaml` 用户代码同步配置所自动管理的 “系统任务”，另一个是用户自定义的 “个人任务” * 系统任务则会在执行 `arcadia update` 更新代码同步配置命令时动态添加或删除，具体如下：定时规则优先从代码文件（注释）内容中获取，由强大的算法提供支持会自动检索识别并进行语法格式校验，如若未识别到或检测到语法错误，届时会随机生成一个每天执行一次的定时规则，你可以在自动添加定时任务之后使用控制面板来自定义修改自动添加的定时任务命令为 `arcadia run xxx`，没有附加任何命令选项，更多用法详见 [CLI 文档教程](/docs/cli/script/run) 定时任务不会重复添加，不过在特殊环境下新增的定时任务会直接覆盖原有的定时任务，例如在迁移后的环境或重新克隆了仓库 # 用户环境变量该命令当前仅支持管理用户配置文件（非数据库）中用 `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` 小时以上的阻塞进程，通过此命令可以释放占用内存以维护项目稳定运行 ```bash title="清理已卡死超过指定小时数的进程" arcadia cleanup ``` # 运行代码文件（脚本） ✍在本篇内容中你将学习到如何运行代码文件这一基础功能。看上去内容很多？其实非常简单。需要特别说明的是，代码文件是各编程语言程序文件的统称，并非所有代码文件都属于脚本类型。 ```sh title="$ arcadia run" ❖ Arcadia CLI - 运行代码文件使用方法： arcadia run [--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 执行命令帮助：文件名(仅scripts目录) 相对路径或绝对路径链接地址 [--options] 命令选项 ``` ## 使用方法 [#使用方法] ```bash arcadia run [--options] ``` ### 文件名称 `name` [#文件名称-name] 仅限 `scripts` 个人目录下的代码文件，并且仅涵盖 `根目录`，你可以把你常用的脚本存放在这里 ### 路径 `path` [#路径-path] 相对路径或绝对路径，支持使用 `.` 或 `./` 作为当前目录和用 `../` 作为上级目录，如果运行本地的个人代码文件则可以省略路径\ 如果运行的是已配置的代码仓库中的代码文件可以使用相对路径，例如 `/arcadia/repo/<仓库目录名称>/example.js` 可以使用 `repo/example.js` 替代 ### 链接地址 `` [#链接地址-url] 运行后代码文件默认保存在 `scripts` 个人目录，支持链接自动纠正功能\ 链接自动纠正功能是当拉取位于远程托管仓库的代码文件时可自动将 *blob* 链接转换为 *raw* 原始文件链接，此功能已应用到整个项目 ### 命令选项 `[--options]` [#命令选项---options] 用于实现一些扩展功能，具体请查看下方的文档内容 *** ## 基础概念 [#基础概念] 默认情况下代码文件在运行后会自动将日志存放在 **log** 目录下的文件夹内，会以目录的形式进行分类目录名中的主要组成部分是代码文件名称，用户导入代码文件的日志目录名称为`<仓库名/raw>_文件名去后缀`，中间用下划线分割目前支持的代码文件类型有 `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`，当存在同名代码文件时仍适用此规则这部分内容与项目命令无关，用于解决代码文件运行时缺少第三方依赖库报错的问题，具体详见 [运行环境](/docs/environment#解决依赖) 文档 *** ## 命令选项 [#命令选项] 使用方法：追加在命令的末尾，熟练后可以使用简写 > 一个高级的应用程序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 运行时 | | `--ts-tsx`, `--use-tsx` | [TypeScript Execute (tsx)](https://tsx.is) | 否 | 使用 tsx 执行 | | `--ts-node`, `--use-ts-node` | [ts-node](https://typestrong.org/ts-node) | 否 | 使用 ts-node 执行 | 通俗易懂的来说并发就是同一时间启动多个任务在后台运行，所以这意味着运行单个任务时使用并发运行命令选项是无意义的行为。\ 这两个命令选项的作用实际上是等价的，为了便于理解才分开设计，你需要加强对功能的理解以作出正确的选择判断。项目命令会根据运行的任务数量动态检测使用场景，届时会判定一些无意义的操作从而报错跳出。\ 例如分组运行和拆分运行就是多任务类型，你应该使用并发运行而不是后台运行。在并发运行代码文件时，会将每个任务的运行日志存储在独特的日志文件中，文件名会使用特殊的标记以进行区分，具体规则如下： * `g` 代表分组运行时的标记、`e` 代表拆分运行时的标记、`t` 表示并发任务数默认为全量并发，请合理使用避免对系统造成的压力过大，可以指定并发线程数来限制同时运行的最大任务数量在 Linux 系统命令行中有一些特殊的字符，例如 `;` `&` 等。如果目标复合变量的分隔符包含这些特殊字符，届时需用英文引号包裹以避免传递错误接下来是一些示例用法，以 `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 ``` 可以简单理解为 `<执行器指令> <执行参数> <目的代码文件> <传递选项>`，例如 `node <执行参数> example.js <传递选项>` 另外需要注意的是 `执行参数` 选项后跟的是一个选项值，例如 `ad run example.js --exec-args "-T --verbose"`，而传递选项会将该选项后的全部内容解析为要传递的参数内容，可以是多个选项，例如 `ad run example.js -- args1 args2`... 该功能由 [global-agent](https://www.npmjs.com/package/global-agent) 实现首先需要全局安装该依赖包，请自行在控制面板《环境配置 - 依赖管理》页面添加模块：生态 `npm`、包名 `global-agent@3` 然后需要配置 `GLOBAL_AGENT_HTTP_PROXY` 环境变量，更多使用方法详其官方文档 ## 终止运行 [#终止运行] ```bash title="终止运行中的代码程序（脚本）" arcadia stop ``` 终止某个或某些正在运行中的代码程序，根据代码文件名称搜索对应的进程并立即杀死，支持终止多进程任务 `` 文件名(仅scripts目录) `` 相对路径或绝对路径 *** ## 守护进程 [#守护进程] 守护进程是可以周期运行的特殊进程，在这里指的是将代码文件设置为后台进程循环运行，当代码文件运行结束或中断时会自动重新运行，适用于需要长期连续运行的代码文件。\ 针对同一个代码文件只可存在一个守护进程，这就意味着当即将被运行的代码文件存在多个任务时不允许设置守护进程。该命令目前仅用于任务启动，请优先通过控制面板进行持久化管理，否则手动在终端命令行启动的任务将无法在控制面板中显示。守护进程模式使用独立的 `rund` 子命令，通过 PM2 将代码文件保持在后台持续运行，进程退出或崩溃后会自动重新拉起。 ```sh title="$ arcadia run" ❖ Arcadia CLI - 运行代码文件（守护进程）使用方法： arcadia rund [--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 执行命令帮助：文件名(仅scripts目录) 相对路径或绝对路径 [--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` | 是 | 启用指数退避重启策略，指定初始延迟毫秒数（非负整数） | ### 管理方法 \[!toc] [#管理方法-toc] * 查看有哪些守护进程正在运行 `pm2 list` * 停止运行 `pm2 stop <任务名>` * 删除任务 `pm2 delete <任务名>` 默认存在二个项目内置的服务 `arcadia_server` `tgbot`，请不要删除它们其中的任何一个 # 后端服务目前前端控制面板由后端服务进行托管运行，项目部分功能的实现依赖于后端服务的持续正常运行，所有守护进程服务会由该命令统一管理 ## 开启/重启服务 [#开启重启服务] ```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 rmlog ``` 默认删除 `7` 天以上的日志，可以通过修改控制面板《个人设置 - 命令》中的 “运行日志保留天数” 更改此默认时间 Arcadia 平台默认不设置自动定时清理日志，你可以在控制面板《定时任务》中创建个人定时任务来实现自动清理 ```bash title="删除指定天数的日志" arcadia rmlog ``` # 更新代码同步配置 # 更新代码同步配置 [#更新代码同步配置] ```bash arcadia update ``` | 子命令 | 含义 | 描述 | | :-----: | :------: | ---------------------- | | `repo` | 更新全部代码仓库 | 更新所有位于 `repo` 目录下的代码仓库 | | `raw` | 更新代码文件 | 更新所有位于 `raw` 目录下的代码文件 | | `extra` | 运行额外更新脚本 | 运行用户自定义的更新脚本 | ## 更新全部代码同步配置 [#更新全部代码同步配置] ```bash arcadia update sync ``` 更新除指定仓库以外的所有内容 ## 更新指定配置或指定路径下的代码仓库 [#更新指定配置或指定路径下的代码仓库] ```bash arcadia update ``` ·` 配置名称`，`` 仓库的相对路径或绝对路径，支持用 `.` 或 `./` 表示当前目录和用 `../` 表示上级目录 ## 常见更新报错 [#常见更新报错] * `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 ``` 同步最新的源代码，更新时长受版本变动大小、下载速度等因素影响 # 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="示例" { "REMOVE_LOG_DAYS_AGO": "14", "ENABLE_UPDATE_EXTRA": "true" } ``` ### 响应 [#响应-1] 无数据，仅返回操作状态。 CLI 配置统一存储于数据库 `config` 表（`module = 'cli'`）中，键名为去除 `CLI_CONFIG_` 前缀的字段名。每次保存后自动生成位于用户配置文件目录下的 `.arcadia_cli_config.sh` 脚本，该脚本会在底层 Shell 命令执行时自动加载。 # Config 配置管理 # 系统配置 ## 获取系统配置 [#获取系统配置] /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" } ``` *** ## 更新系统配置 [#更新系统配置] /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] 返回数组对象 ```json title="示例" [ { "timestamp": 1773161661000, "taskId": 1, "taskName": "更新仓库", "taskType": "user", "duration": 21749, "success": true }, { "timestamp": 1773233647000, "taskId": 1, "taskName": "更新仓库", "taskType": "user", "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 ## 请求 [#请求] ## 响应 [#响应] * CronTasksData * 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": "", "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": "", "is_running": true }, ... ], "total": 5, "page": 1, "size": 20 } ``` 默认倒序返回 # 运行 /cron/run ## 请求 [#请求] 支持批量操作 # 查询运行中的任务 /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("") } 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/terminate ## 请求 [#请求] 支持批量操作 # 修改 /cron ## 请求 [#请求] * CronTasksConfig 支持批量操作（改成数组） ## 响应 [#响应] 返回布尔值，如果是批量创建只要有一个失败就返回 `false` # 新增 /dependency ## 请求 [#请求] ## 响应 [#响应] 返回新创建的依赖记录，字段同 [数据关系模型](./schema)。 ## 错误 [#错误] | 错误信息 | 说明 | | ------------------------ | -------------------------- | | `name 不能为空` | name 为空字符串 | | `{ecosystem}/{name} 已存在` | 相同 ecosystem + name 的记录已存在 | # 删除 /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] 返回数组对象 # 名称检查 /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 为该任务缓存的日志内容 | # 执行 Shell 命令 /exec/cmd ## 请求 [#请求] ## 响应 [#响应] 返回事件 ID 字符串，关于如何获取日志详见 [获取实时日志](/docs/api/websocket/log)。 # 运行代码文件 ## 运行 [#运行] /exec/file ### 请求 [#请求] ### 响应 [#响应] 返回事件 ID 字符串，关于如何获取日志详见 [获取实时日志](/docs/api/websocket/log)。 ## 调试运行 [#调试运行] /exec/file/debug 会创建临时文件并在运行完毕后自动清理，不修改原始代码文件内容。 ### 请求 [#请求-1] ### 响应 [#响应-1] 返回事件 ID 字符串，关于如何获取日志详见 [获取实时日志](/docs/api/websocket/log)。 ## 终止运行 [#终止运行] /exec/file/stop ### 请求 [#请求-2] ### 响应 [#响应-2] 返回事件 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/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` 传参，暂不支持上传目录 # 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/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/count ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" ``` # 删除 /message/delete ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" ``` # 获取详情 /message/detail ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" ``` # 消息中心 # 获取列表 /message/list ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" ``` # 获取分页 /message/page ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" ``` # 更新状态 /message/status ## 请求 [#请求] ## 响应 [#响应] ```json title="示例" ``` # 创建 /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` | 列出文件目录 | ## 权限键一览 [#权限键一览] 定时任务 (cron) 环境变量 (env) 文件系统 (file) 命令执行 (exec) | 权限键 | 说明 | 默认启用 | 危险 | | ------------- | ----------------- | :--: | :-: | | `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` | **危险权限**（⚠️）在创建令牌时默认禁用，需显式传入权限键方可启用。请仅在必要时授予，并严格控制令牌的分发范围。 # 更新 /token ## 请求 [#请求] ## 响应 [#响应] 参考[获取列表响应](/docs/api/token/list#响应) # 登录认证 /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`\ 事件名称：`depOperateResult` 根据业务场景返回部分字段，不返回完整记录数据。 # WebSocket # 获取实时日志持续推送日志数据接口路径：`/api/ws`\ 事件名称：`runLog` # Cron 定时任务 # 创建 {/* 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. */} # Env 环境变量目前为环境变量设计了三种类型，如果你还不理解这三种类型的区别请先参考[此描述](/docs/configuration#1-环境变量--控制面板)并了解前端界面设计\ 为了提高开发效率已将部分接口的传参设计为了更容易理解的形式，建议使用前先学习项目[数据模型](/docs/api/env/schema)设计 # 更改状态 {/* 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 命令执行 # 执行 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 文件系统 # 获取文件内容 {/* 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. */} # 代码文件通过下载文件 `Wget` 的方式扩展本地脚本，存放在 `/arcadia/raw` 目录下 ## 环境配置项 [#环境配置项] | 名称 | 必填 | 类型 | 默认值 | 描述 | | :------------: | :-: | :-------: | :----: | -------------------------------- | | `name` | 是 | `string` | 无 | 代码文件名称 | | `url` | 是 | `string` | 无 | 代码文件地址 | | `fileName` | 否 | `string` | 无 | 指定文件名称，需要包含后缀格式，不填则自动截取链接地址中的文件名 | | `enable` | 否 | `boolean` | `true` | 是否启用该配置 | | `cronSettings` | 否 | `object` | 无 | 定时任务设置 | * cronSettings ## 填法示例 [#填法示例] ```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 表达式` ，如若没有或者未识别到那么将随机指定一个每天执行一次的定时规则大部分脚本都位于 [GitHub](https://github.com) 仓库上，如果你的设备不能有效与其连通可以尝试使用 CDN 进行加速例如 [jsDelivr](https://www.jsdelivr.com/github)，不过更新可能会因为缓存而存在一定的延迟 ## 配置依赖文件 [#配置依赖文件] 根据配置代码文件的原理，对应**raw**目录下只允许存在已配置的脚本，配置以外的文件会被删除，如果运行此处的脚本需要额外的依赖文件那么你需要配置此项 ```yaml gobal: rawDependencyFilter: '' # string ``` 基于 [**grep**](https://www.runoob.com/linux/linux-comm-grep.html) 指令进行过滤（默认使用 `-E` 命令选项用于匹配多个表达式），支持正则表达式。如果要匹配多个表达式，那么根据该指令规范你需要使用 `|` 字符来进行分割，与代码仓库的定时任务黑白名单配置用法相同 ## 删除已配置的代码文件 [#删除已配置的代码文件] 删除配置文件中的相关配置项即可，在更新后会自动删除脚本和定时，无需手动删除 ## 快速添加配置 [#快速添加配置] 详见 CLI 文档教程 [添加代码文件配置](/docs/cli/config/raw) # 代码仓库通过克隆仓库 `Git` 的方式扩展本地脚本，存放在 `/arcadia/repo` 目录下 ## 主配置项 [#主配置项] * 关于 `scriptsPath` 根据导入工作原理，匹配文件不会递归仓库下的所有目录，不设置该项或键值为空即代表默认根目录如果你想配置匹配指定目录下的文件则需要手动配置，多个路径需要使用空格来进行分割，仓库根目录用 `/` 来表示 ```yaml title="示例" scriptsPath: "/ test" ``` 如上，最终会匹配位于仓库根目录和 `test` 子目录下的所有文件即 `/arcadia/repo//*` 和 `/arcadia/repo//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` 如果你启用了定时文件配置那么请尽可能不要忽略此配置项，因为如果不配置该项可能会导致自动添加一些无用的定时任务基于 [**grep**](https://www.runoob.com/linux/linux-comm-grep.html) 指令进行过滤（默认使用 `-E` 命令选项用于匹配多个表达式），支持正则表达式。如果要匹配多个表达式，那么根据该指令规范你需要使用 `|` 字符来进行分割，你可以先在本地调试好再进行配置，例如 `ls | grep -E ""`。如果你想学习正则表达式和该指令你可以看看 [《基础正则表达式》](https://www.junmajinlong.com/shell/regex_basic) 这篇文章根据 YAML 语法规范，如果使用双引号来包裹键值那么会使转义字符生效，这样在读取与过滤规则相关的键值对时会出现问题 SSH 配置需要用户自行上传私钥部分代码托管平台例如 `GitHub` 取消了通过账号密码对私有仓库的访问\ 届时仅支持令牌访问，具体创建令牌的方法详见 [管理个人访问令牌](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 认证方式二选一，不要同时配置 ## 填法示例 [#填法示例] ```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` 命令来使该配置生效针对同一个仓库直接修改 `url` 键值对即可，同一个仓库指的是两个不同的地址所指向的仓库拥有相同的用户名和仓库名，否则将被视为一个新的仓库大部分代码仓库都托管于 [GitHub](https://github.com) 上，如果你的设备不能有效与其连通则需要使用代理 ## 删除已配置的代码仓库 [#删除已配置的代码仓库] 1\). 手动删除配置文件中的仓库配置 2\). 手动删除相关定时任务，你可以通过控制面板的定时任务页进行操作，在任务名称列设置过滤后批量删除 3\). 手动删除本地仓库文件，一般在 **repo** 目录下，文件夹名格式为 `作者名_仓库名` ## 关于定时任务 [#关于定时任务] 根据工作原理，你可能会遇到下方提到的特殊情况，你应该了解这些情况并且知道如何解决 1\). 修改定时过滤规则并不会影响已经添加的定时任务，所以如果有不合适的定时任务则需要你手动进行删除。 2\). 匹配定时任务仅支持处理基于文件增删变动的情况，这意味着如果在首次克隆仓库之后再配置启用仓库定时任务是无效的，因为没有检测到文件变动。不过你可以通过删除本地仓库目录来解决这个问题，这样在下次更新时就会因为克隆仓库而检测到文件变动，不过这样会覆盖用户关于导入定时任务的手动修改数据，所以最好从一开始就确定使用需求。 ## 快速添加配置 [#快速添加配置] 详见 CLI 文档教程 [添加代码仓库配置](/docs/cli/config/repo)