AgentbaseDocs
文档目录

函数

函数(Functions)是 Agentbase 2.10.0 提供的事件驱动、多语言 Serverless 服务端代码执行引擎。它支持通过 HTTP 请求直接调用、按内部业务事件(如数据库新增工单、用户注册、文件上传)自动触发或按 Cron 表达式定时执行,并提供从源码构建(.tar.gz / Git)到 **Java 17 预构建 JAR 包直接部署(artifactMode=java-jar)、去重执行路径查询(Execution Paths)以及云沙箱(ACS Sandbox)容器组资源监控**的完整生产级能力。

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

功能概述

在构建企业级 AI 与智能体应用(如项目 企业智能客服与知识中台 enterprise-ai-hub-210)时,许多自定义业务逻辑需要运行在安全受控的服务端沙箱中:例如当客户在 customer_tickets 表提交紧急工单(TK-20261022-001)时,自动触发函数调用企业内部 ERP 接口核验合同等级;或者将复杂的 Java 17 企微/钉钉加解密逻辑打包为独立工具函数供智能体调用。

Agentbase Functions 围绕企业高并发与高安全标准提供四大核心特性:

核心能力维度控制台页签位置关键技术规格(2.10.0 基线)适用研发与运维场景
创建与部署(Deployments)函数详情 Deployments三种来源:Git 仓库、模板库、手动上传(.tar.gz 源码或 java-17.0 预构建 .jar)持续集成发布、一键切换激活版本(Activate)与回滚历史版本
执行与路径回查(Executions)函数详情 Executions支持立即/定时手动触发;支持去重执行路径分页与 path/pathMatch/method 过滤在线接口联调、按具体 REST 子路径(如 /webhook/erp-sync)精准排查慢请求与报错
算力规格与监控(Usage)函数详情 Usage · Settings支持配置 CPU/内存规格(runtimeSpecification)与副本数(runtimeReplicas);支持平台默认规格观察执行次数、平均耗时及 ACS 云沙箱容器组的 CPU/内存/网络/磁盘实时曲线
触发器与变量(Settings)函数详情 Settings · Domains事件触发(Events)、定时任务(Cron Schedule)、函数级变量(与项目全局变量自动合并注入)编排事件驱动自动化工作流、绑定函数专属自定义域名

核心概念与架构

下图展示了 Functions 从代码/JAR 包部署、三种触发方式(HTTP / 事件 / Cron)、项目上下文与变量注入,到在受限身份 ACS 云沙箱中执行并产出路径索引与监控指标的全链路架构:

flowchart TB
    subgraph DeploySources["部署来源与产物模式 (Deployment)"]
        GitSrc["1. Git 仓库连接<br/>GitHub 分支/Commit 自动构建"]
        TplSrc["2. 官方模板库 (Templates)<br/>Starter 快速开始 / 精选模板"]
        ManualSrc["3. Manual 手动上传<br/>a) artifactMode=source (.tar.gz 源码包)<br/>b) artifactMode=java-jar (Java 17 预构建 JAR, 受有效大小上限约束)"]
    end

    subgraph TriggerPlane["三大触发入口 (Triggers)"]
        HTTPTrig["HTTP / SDK / 自定义域名调用<br/>(严禁 Query String 传 Key, 强制 Header 鉴权)"]
        EventTrig["平台内部事件触发 (Events)<br/>例如 databases.*.tables.*.rows.create"]
        CronTrig["Cron 定时调度 (Schedule)<br/>标准 Cron 表达式周期触发"]
    end

    subgraph SandboxRuntime["执行面:OpenRuntimes / ACS 云沙箱 (Restricted Identity)"]
        ContextInject["自动注入项目上下文:<br/>项目 Global variables + 函数级 Variables (同名覆盖提示)<br/>+ runtimeSpecification (CPU/内存) + runtimeReplicas (多副本)"]
        ExecEngine["受限身份容器执行 (Node / Python / java-17.0 等)<br/>出站 SSRF 防护 + 平台错误 (502/503/504) 与业务错误 (500) 隔离"]
        ContextInject --> ExecEngine
    end

    subgraph ObsAndQuery["执行记录与容器监控"]
        PathIndex["去重执行路径查询 (Execution Paths)<br/>path + pathMatch (exact/regex) + method 过滤"]
        ACSMonitor["Usage 与 ACS 容器组监控<br/>执行次数 / 耗时 + CPU / 内存 / 网络 / 磁盘水位"]
    end

    GitSrc --> SandboxRuntime
    TplSrc --> SandboxRuntime
    ManualSrc --> SandboxRuntime
    HTTPTrig --> SandboxRuntime
    EventTrig --> SandboxRuntime
    CronTrig --> SandboxRuntime
    ExecEngine --> PathIndex
    ExecEngine --> ACSMonitor

1. 四大核心对象模型定义

核心对象生命周期与唯一标识关键属性与架构说明
Function(函数定义)归属 Project,拥有唯一 $id定义运行时语言(runtime,创建后固定)、算力规格(runtimeSpecification)、实例副本数(runtimeReplicas)、执行权限(execute ACL)、超时时间(timeout)、触发事件与 Cron 计划。
Deployment(部署版本)归属 Function,每次上传/提交生成新 $id承载一次具体的代码或预构建 JAR 产物。经历 waiting → building → ready / failed 构建流转;同一时刻仅有一个 ready 部署处于 Active(当前激活) 状态对外提供服务。
Execution(单次执行)归属 Function,每次触发生成唯一记录记录单次调用的请求方法(method)、请求路径(path)、耗时(duration)、HTTP 响应状态码(responseStatusCode)、标准输出(logs)与错误输出(errors)。
Execution Path(去重执行路径)服务端自动按请求 path 聚合将海量 Execution 记录按实际访问的子路径(如 /v1/sync、/v1/callback)去重归类,支持服务端分页与正则/方法过滤。

2. 源码构建模式(source)与 Java 17 预构建 JAR 模式(java-jar)对比

在 Agentbase 2.10.0 中,针对企业广泛使用的 java-17.0 运行时,提供了两种截然不同的部署产物模式(artifactMode):

对比维度源码包构建模式(artifactMode = source)Java 17 预构建 JAR 模式(artifactMode = java-jar,2.10.0 新增)
适用运行时全部受支持运行时(Node.js、Python、PHP、Ruby、Deno、Go、java-17.0 等)**仅限 java-17.0 运行时**
上传产物格式.tar.gz 源码压缩包在本地或企业 CI 流水线预先编译打包好的 **.jar 文件**
构建与入口机制容器内执行 install command 拉取依赖并编译源码,按自定义 entrypoint 启动免除云端源码编译,直接使用预构建 JAR 作为部署产物,使用 manifest 的 Main-Class;Index.java 仅为部署记录兼容标识
包体积限制与计量受通用计算源码包上限(_APP_COMPUTE_SIZE_LIMIT / 套餐 deploymentSize)约束由 _APP_FUNCTIONS_JAR_SIZE_LIMIT(默认 100,000,000 字节)与套餐 deploymentSize 共同限制,以有效上限为准

角色、入口与关联关系

1. 控制台导航路径与权限要求

2. 函数级变量与项目全局变量的注入优先级

函数执行时,平台会自动将环境变量注入容器进程中,变量来源包含两层:

功能详解与操作指南

1. 创建云函数(三种来源与算力规格配置)

点击 Functions 列表页右上角的 Create function 进入创建向导(/functions/create-function),向导提供且仅提供以下三种创建方式:

方式一:通过手动配置创建(Manual,支持 .tar.gz 源码或 Java 17 .jar)

配置项字段必填/选填参数约束与生产配置建议
Name(函数名称)必填输入清晰的业务名称(如 erp-ticket-escalation-fn),可选自定义 **Function ID($id)**。
Runtime(运行时)必选从当前部署实例允许的运行时列表中选择(如 node-18.0、python-3.11、**java-17.0**)。注意:函数创建后运行时类型不可直接切换。
Artifact Mode(产物模式)必选(Java 17)当 Runtime 选择 java-17.0 时,可选择 **源码包(source) 或 预构建 JAR(java-jar)**:<br/>• 选 source:上传 .tar.gz 源码包,填写 entrypoint 与 install command;<br/>• 选 java-jar:上传满足有效大小上限的 .jar 包,应用入口取自 manifest 的 Main-Class。
**CPU / 内存规格(runtimeSpecification)**必选选择函数执行容器的算力规格(如 0.5C / 1G、1C / 2G 等)。若平台管理员配置了默认执行规格(defaultRuntimeSpecification),向导会自动预选该规格;若无可用规格请联系管理员发布 execution profile。
**副本数(runtimeReplicas)**必选设置并发承载的沙箱实例副本数,高并发生产函数建议配置多副本以消除冷启动毛刺。
Execute Access(执行权限)选填配置允许直接触发该函数的客户端角色(如 users);若仅由后端 API Key 或内部事件触发,保持为空(默认拒绝客户端直接调用)最安全。

方式二:从官方模板创建(Templates)

方式三:连接 Git 仓库创建(Git Repository)

2. 管理部署版本(Deployments)与一键回滚

进入具体函数详情页(/functions/function-{function}),默认展示 Deployments 页签:

3. 在线触发执行(Execute)与去重执行路径查询(Execution Paths)

切换到函数详情页的 Executions 页签(路径 /functions/function-{function}/executions):

A. 在线手动调试或排期执行

B. 按去重执行路径(Execution Paths)检索与排障(2.10.0 增强)

当单个函数通过内部路由承载了数十个业务子接口时,使用 执行路径查询 可快速定位特定接口的执行情况:

C. 区分平台沙箱故障与业务代码异常

在查看失败的执行记录详情时,请根据响应状态码与日志面板精准定界:

响应状态码故障归属分类具体含义与排障方向
500业务代码失败(Business Failure)函数容器已正常启动,但你的业务代码抛出了未捕获异常或主动返回了 500。Console 会完整保留该次执行的业务日志(Logs / Errors),请直接根据堆栈信息修复代码。
503平台失败:沙箱创建异常底层计算集群算力不足或沙箱创建失败。请检查 ACS 资源池水位或联系平台管理员。
504平台失败:启动或执行超时容器冷启动超时,或业务代码执行耗时超过了函数 Settings → Timeout 设定的秒数上限(如等待下游慢接口)。请调高函数 Timeout 或优化下游调用。
502平台失败:执行链路异常网关与运行时沙箱之间的内部通信链路中断,或者是用户启动命令违反了受限身份安全条件被沙箱直接终止。

4. 配置定时任务(Schedule)、事件触发、监控与自定义域名

确认执行规格

创建向导会优先预选当前项目可用的平台默认规格。提交前检查 CPU、内存和副本数是否适合实际负载;手工选择的有效规格优先于默认值。如果没有可用的平台默认规格,按页面列出的可用规格选择,不要直接照抄其他项目的配置。

默认值只影响新建 Function;已有函数不会随平台默认值改变。编辑已有函数时确认保留原执行规格,尤其不要在只调整副本数时顺带改掉规格。执行规格与构建资源是不同配置,调整执行规格不代表构建资源同时改变,也不代表实例已预热。

上传 Java 17 预构建 JAR

适用于已在本地或 CI 构建好的 Java HTTP 服务。准备支持 Java 17 的可执行 JAR:manifest 必须声明 Main-Class,包内必须包含对应入口类;应用监听端口 3000 并提供 /__opr/health 健康检查。仅执行后退出的命令行 JAR 不能作为函数 HTTP 服务使用。

检查点可以确认什么下一步
上传进度达到 100%文件传输结束等待创建部署请求返回,不要重复上传
已返回部署记录服务已接收部署等待状态达到 ready;failed/canceled 时查看日志
部署 ready产物准备完成检查当前激活部署是否为本次部署
激活部署一致且请求结果符合预期本次代码已实际执行再启用业务流量或定时任务

无法提交时先检查运行时、上传模式、JAR 大小及 manifest;部署失败时查看构建日志;部署 ready 但调用失败时检查端口、健康检查、变量、执行权限和执行日志。不要把上传成功当作上线成功。

按 Path 和 Method 排查执行

在函数详情 Executions → 自定义筛选 中填写 Path,选择精确匹配或正则匹配,再按需选择 Method,应用筛选后从第一页查看结果。刷新会保留筛选条件;排查完使用清除操作恢复完整列表。

排查目标示例条件注意事项
某个完整请求路径Path 精确匹配 /articles/42查询字符串参与匹配,/articles/42?draft=1 是不同路径
一组编号路径Path 正则 ^/articles/[0-9]+$不额外包裹 /…/ 分隔符;此表达式不匹配带查询字符串的路径
只看读取请求Method 选择 GET方法与路径条件同时生效,先核对真实请求方法

空列表只表示当前条件未命中;先清除筛选核对记录确实存在,再逐项加回条件。waiting / processing 仍表示等待或处理中,不能仅凭已过 timeout 就当作 failed。服务实际记录失败后才会进入失败筛选。运行中的记录不能删除;completed、failed 可删除记录,删除 scheduled 记录会取消对应计划执行。

常见问题与排障

Q1:外部系统通过 URL Query String(如 ?key=standard_xxx)调用受保护的云函数为什么返回 401 鉴权失败?

原因与排查步骤: 出于严密的安全合规要求,Agentbase 禁止通过 URL Query String 传递 Function API Key(因为 URL 参数极易在浏览器历史、反向代理 Access Log 与监控链路中明文泄露凭据)。调用受保护的云函数时,必须将密钥放在受保护的 HTTP 请求头中传递(如 X-Appwrite-Key: standard_...),或使用平台注入的运行时内部认证路径。

Q2:部署或运行函数时报错“不满足受限身份安全条件(Restricted Identity)”,为什么没有自动用 root 权限跑起来?

原因与排查步骤: Agentbase 的 Functions 与 Sites 容器强制执行受限非特权身份运行 + Fail-Closed(失败即拒绝)策略:当你的构建脚本、启动命令或二进制文件尝试执行需要高权限的操作(如修改系统目录、绑定特权端口或切换系统用户)时,沙箱会立即终止并直接报错,**绝不会静默回退为高权限 root 身份执行**。请将临时文件读写路径全部指向工作目录或 /tmp,并移除任何提权指令后重新部署。

Q3:使用 Java 17 预构建 JAR 模式(artifactMode=java-jar)上传部署包时需要注意什么?

原因与排查步骤:

相关文档