组织项目治理(不活跃查询 / 批量删除 / 恢复)
这是什么 / 何时用
组织 Owner 的一组项目生命周期治理能力:查询本组织不活跃项目、dry run 预检后批量发起延迟删除、查询处于删除生命周期的项目、恢复仍处于 pending_purge 状态的项目。2.6.0 的 agentbase-web-sdk@2.8.0 与 agentbase-node-sdk@2.8.0 均包含对应方法(Web/Node 的 Projects service);无 SDK 的受控集成可用同形 REST。
前置
| 项 | 说明 |
|---|---|
| 角色 | 当前账号必须是目标组织 Owner;普通组织成员无权限 |
| 认证 | Owner Session(交互首选)、短期 Owner JWT(自动化首选,account.createJWT 签发,默认 15 分钟);Organization API Key 仅当目标环境已交付且具备 projects.read/projects.write |
| 客户端 | 管理面请求指向 Console project(setProject('console') 或环境实际 Console project ID),并 setOrganization(teamId) 声明组织(X-Appwrite-Organization 头) |
| Scope | 查询类(不活跃、删除列表)需 projects.read;批量删除与恢复需 projects.write |
普通项目 API Key 不能替代组织级凭据;SDK 中存在组织 Key 方法不代表目标实例开放对应创建入口。Key 不可用时不阻塞治理,改用 Session / JWT。
使用骨架
固定流程(删除是高风险操作,不要自动化到「查询结果直接删」):
- 查询候选:
Projects.listInactiveByOrganization分页拉取不活跃项目,人工核对。 - 固定清单:由 Owner 明确圈定 1–50 个项目 ID 与审计原因。
- dry run 预检:
batchReleaseByOrganization({ dryRun: true }),核对逐项目results与summary(accepted/rejected/skipped)。 - 二次确认后正式提交:
dryRun: false,同一清单、同一原因。 - 跟踪删除生命周期:
listDeletionsByOrganization按deletedAt倒序查看pending_purge/purging/purge_failed。 - 恢复(可选):重新读取最新状态,确认目标项目仍为
pending_purge,由 Owner 指定单个projectId调restoreDeletionByOrganization;恢复成功清除删除元数据。
Console 等价入口:组织「项目清理」页 <console-origin>/console/organization-{organizationId}/project-cleanup;Console 直接提交正式删除(展示全部/部分接受/拒绝与失败摘要),需要逐项目预检结果时用 SDK / REST。
关键参数与返回
方法与 REST 对照
| 操作 | SDK 方法(Web/Node Projects) | REST | Scope |
|---|---|---|---|
| 查询不活跃项目 | listInactiveByOrganization | GET /v1/teams/{teamId}/projects/inactive | projects.read |
| 预检 / 批量删除 | batchReleaseByOrganization | POST /v1/teams/{teamId}/projects/batch-release | projects.write |
| 查询删除生命周期 | listDeletionsByOrganization | GET /v1/teams/{teamId}/projects/deletions | projects.read |
| 恢复待删除项目 | restoreDeletionByOrganization | DELETE /v1/teams/{teamId}/projects/{projectId}/deletion | projects.write |
参数要点
listInactiveByOrganization:teamId(canonical Team ID)+inactiveDays(1–365,必填)+graceDays?(默认 7,创建后宽限期)+limit?(1–500,默认 100)+cursor?(上一页nextCursor原样回传)。只配置这些参数,不传 criteria / signals / preset 之类筛选。batchReleaseByOrganization:teamId+projectIds[](1–50 个)+dryRun?+reason?(审计原因);返回requestId、逐项目results与summary。listDeletionsByOrganization:teamId+limit?(1–100,默认 25)+offset?。restoreDeletionByOrganization:teamId+projectId;返回{ status: 'restored', projectId, requestId }。
返回与活跃度语义
- 不活跃判定统一使用项目文档的
accessedAt(真实项目级 API 请求、经路由解析的自定义域请求、Function 执行 / 数据源同步 / 计划消息等真实工作负载会更新;/health与例行维护扫描不会)。写入有约 24 小时合并窗口,判定在inactiveDays基础上加同等安全余量;无accessedAt时以$createdAt为基准。 - 响应含
inactiveDays、projects[]、total、scanned,有下一页时含nextCursor;total是本次有界扫描(每请求最多扫 50 个项目)发现的匹配数,不是组织级精确总数。候选里每个项目带lastResourceActivityAt、inactiveSince等。 - 删除列表项含
projectId、name、teamId、deletionStatus、deletedAt、purgeAt及可能缺省的deletedBy、reason、requestId、error。
错误与边界
teamId必须是 canonical Team ID;setOrganization()/X-Appwrite-Organization也使用该值。Console 公开 organizationId 不能直接当teamId。- 只有
pending_purge项目可恢复;purging、purge_failed或仍在正常活动中的项目返回 409;项目不存在或不属于当前组织返回 404(防跨组织枚举)。 - 恢复不是列表接口的批量后处理:每次只恢复 Owner 明确指定的单个项目。
console项目与已进入删除生命周期的项目不会出现在不活跃候选中。- 正式提交会区分全部接受、部分接受与全部拒绝;
purge_failed项保留在删除列表并带失败摘要。 - 不要根据动态查询结果自动删除或恢复;dry run 与二次确认是流程必选项。
SDK 类别差异
- Web Client SDK:浏览器内用 Owner Session;
new Client().setEndpoint(...).setProject('console').setOrganization(teamId)后new Projects(client)调用四方法;不放置任何组织 Key。 - Node Server SDK:短期脚本用
account.createEmailPasswordSession后client.setSession(session.secret).setOrganization(teamId),或setJWT(...);CI 用短期 Owner JWT。 - Console SDK:本能力不经 Console SDK 方法面(Console 提供等价页面)。
- Java(Server/Console):
io.agentbase/io.agentbase.console的Projects类含同形四方法(listInactiveByOrganization等),认证与setOrganization用法同上。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
查询不活跃项目
listInactiveByOrganization 分页拉取候选,人工核对后固定清单。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const { Account, Client, Projects } = require('agentbase-node-sdk');
const teamId = process.env.APPBASE_ORGANIZATION_TEAM_ID; // canonical Team ID
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT)
.setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID || 'console'); // 管理面指向 Console project
const account = new Account(client);
const session = await account.createEmailPasswordSession({ // 当前账号必须是组织 Owner
email: process.env.APPBASE_OWNER_EMAIL,
password: process.env.APPBASE_OWNER_PASSWORD
});
client.setSession(session.secret).setOrganization(teamId); // 或 setJWT(shortLivedOwnerJwt)
const projects = new Projects(client);
const page = await projects.listInactiveByOrganization({
teamId,
inactiveDays: 90, // 必填,1-365
graceDays: 7, // 可选,默认 7
limit: 50 // 可选,1-500,默认 100
// cursor: 上一页 nextCursor 原样回传
});
// page: { inactiveDays, projects[], total, scanned, nextCursor? }
// total 是本次有界扫描(每请求最多扫 50 个项目)的匹配数,不是组织级精确总数import { Client, Projects } from 'agentbase-web-sdk'; // 浏览器内 Owner Session,不放组织 Key
const teamId = 'canonical-team-id';
const organizationClient = new Client()
.setEndpoint(import.meta.env.VITE_APPBASE_ENDPOINT)
.setProject(import.meta.env.VITE_APPWRITE_CONSOLE_PROJECT_ID || 'console')
.setOrganization(teamId);
const projects = new Projects(organizationClient);
const candidates = await projects.listInactiveByOrganization({ teamId, inactiveDays: 90 });import io.agentbase.services.Projects;
// client 为 io.agentbase.Client:setProject('console') 后认证用 Owner Session / 短期 Owner JWT(setSession / setJWT),
// 并 client.setOrganization(teamId) 声明组织(X-Appwrite-Organization)
Projects projects = new Projects(client);
var page = projects.listInactiveByOrganization(
teamId,
90L, // 必填,1-365
7L, // 可选,默认 7
50L, // 可选,1-500,默认 100
null); // cursor:传上一页 nextCursor 原样回传
// page: { inactiveDays, projects[], total, scanned, nextCursor? };total 是有界扫描匹配数,不是组织级精确总数from agentbase.services.projects import Projects
# client 为 Server SDK Client:set_project('console') 后凭 Owner Session / 短期 Owner JWT(set_session / set_jwt),
# 并 client.set_organization(team_id) 声明组织(X-Appwrite-Organization)
projects = Projects(client)
page = projects.list_inactive_by_organization(
team_id=team_id,
inactive_days=90, # 必填,1-365
grace_days=7, # 可选,默认 7
limit=50, # 可选,1-500,默认 100;cursor 传上一页 nextCursor 原样回传
)
# page: { inactiveDays, projects[], total, scanned, nextCursor? };total 是有界扫描匹配数,不是组织级精确总数projects := agentbase.NewProjects(cl) // facade 构造器;cl 指向 Console project,Owner 凭据经 WithSession/WithJWT、组织经 WithOrganization(teamId) 装载
page, err := projects.ListInactiveByOrganization(teamId, 90,
projects.WithListInactiveByOrganizationGraceDays(7), // 可选,默认 7
projects.WithListInactiveByOrganizationLimit(50)) // 可选,1-500,默认 100;Cursor 传上一页 NextCursor 原样回传
// page: { InactiveDays, Projects[], Total, Scanned, NextCursor? };InactiveDays 按位置传,GraceDays / Limit / Cursor 用 WithListInactiveByOrganization*curl -sS --get "$APPBASE_ENDPOINT/teams/$APPBASE_ORGANIZATION_TEAM_ID/projects/inactive" \
-H 'X-Appwrite-Project: console' \
-H "X-Appwrite-JWT: $APPBASE_OWNER_JWT" \
-H "X-Appwrite-Organization: $APPBASE_ORGANIZATION_TEAM_ID" \
--data-urlencode 'inactiveDays=90' \
--data-urlencode 'graceDays=7' \
--data-urlencode 'limit=50'
# 已交付 Organization Key 的环境可换 -H "X-Appwrite-Key: $APPBASE_ORGANIZATION_API_KEY"(仍须保留 X-Appwrite-Organization)dry run 预检与批量删除
batchReleaseByOrganization:Owner 固定 1–50 个项目 ID 与审计原因,先 dryRun: true,二次确认后 dryRun: false。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
// client / projects 初始化见上一卡;projectIds 由 Owner 圈定固定清单(1-50 个),不从查询结果直接全选
const fixedProjectIds = ['project-a', 'project-b'];
const reason = '长期无资源活动,业务负责人已确认';
const preview = await projects.batchReleaseByOrganization({
teamId, projectIds: fixedProjectIds, dryRun: true, reason
});
// preview: { requestId, results[], summary: { accepted, rejected, skipped } }
if (preview.summary.rejected > 0 || preview.summary.skipped > 0) {
throw new Error('预检未全部通过,重新核对固定清单');
}
const submitted = await projects.batchReleaseByOrganization({
teamId, projectIds: fixedProjectIds, dryRun: false, reason // 二次确认后同一清单正式提交
});const preview = await projects.batchReleaseByOrganization({
teamId,
projectIds: candidates.projects.map((project) => project.projectId),
dryRun: true,
reason: '长期无资源活动,业务负责人已确认'
}); // 正式提交同样以固定清单 + dryRun: false 调用,流程同 Node 页签// projects / client 构造见上一卡;projectIds 由 Owner 圈定固定清单(1-50 个),不从查询结果直接全选
var preview = projects.batchReleaseByOrganization(
teamId,
List.of("project-a", "project-b"),
true, // dryRun
"长期无资源活动,业务负责人已确认"); // reason
// preview: { requestId, results[], summary: { accepted, rejected, skipped } }
// 预检未全部通过时重新核对固定清单;通过并二次确认后:同一清单、同一原因,dryRun 改 false 正式提交# projects / client 构造见上一卡;project_ids 由 Owner 圈定固定清单(1-50 个),不从查询结果直接全选
preview = projects.batch_release_by_organization(
team_id=team_id,
project_ids=['project-a', 'project-b'],
dry_run=True,
reason='长期无资源活动,业务负责人已确认')
# preview: { requestId, results[], summary: { accepted, rejected, skipped } }
# 预检未全部通过时重新核对固定清单;通过并二次确认后:同一清单、同一原因,dry_run=False 正式提交// projects / cl 构造见上一卡;projectIds 由 Owner 圈定固定清单(1-50 个),不从查询结果直接全选
preview, err := projects.BatchReleaseByOrganization(teamId, []string{"project-a", "project-b"},
projects.WithBatchReleaseByOrganizationDryRun(true),
projects.WithBatchReleaseByOrganizationReason("长期无资源活动,业务负责人已确认"))
// preview: { RequestId, Results[], Summary{Accepted, Rejected, Skipped} }
// 预检未全部通过时重新核对固定清单;通过并二次确认后:同一清单、同一原因,DryRun 改 false 正式提交curl -sS -X POST "$APPBASE_ENDPOINT/teams/$APPBASE_ORGANIZATION_TEAM_ID/projects/batch-release" \
-H 'X-Appwrite-Project: console' \
-H "X-Appwrite-JWT: $APPBASE_OWNER_JWT" \
-H "X-Appwrite-Organization: $APPBASE_ORGANIZATION_TEAM_ID" \
-H 'Content-Type: application/json' \
-d '{"projectIds":["project-a","project-b"],"dryRun":true,"reason":"长期无资源活动,业务负责人已确认"}'
# 预检通过并二次确认后:同一清单、同一原因,dryRun 改为 false 正式提交删除生命周期与恢复
listDeletionsByOrganization 按 deletedAt 倒序查看 pending_purge / purging / purge_failed;仅 pending_purge 可由 Owner 指定单个项目恢复。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
// client / projects 初始化见第一卡
const deletions = await projects.listDeletionsByOrganization({ teamId, limit: 25, offset: 0 });
// deletions.projects[]: { projectId, name, teamId, deletionStatus, deletedAt, purgeAt, ... }
const selectedProjectId = 'project-id-confirmed-by-owner'; // Owner 明确指定,不要自动选列表首个
const selected = deletions.projects.find((p) => p.projectId === selectedProjectId);
if (!selected || selected.deletionStatus !== 'pending_purge') {
throw new Error('指定项目不在当前页,或已不可恢复');
}
const restored = await projects.restoreDeletionByOrganization({ teamId, projectId: selectedProjectId });
// 成功返回 { status: 'restored', projectId, requestId };409 表示状态已变化,重新查询不要重试const deletions = await projects.listDeletionsByOrganization({ teamId, limit: 25, offset: 0 });
const selected = deletions.projects.find(
(project) => project.projectId === 'project-id-confirmed-by-owner'
);
if (!selected || selected.deletionStatus !== 'pending_purge') {
throw new Error('Owner 指定的项目不存在于当前页,或已不可恢复');
}
await projects.restoreDeletionByOrganization({ teamId, projectId: selected.projectId });var deletions = projects.listDeletionsByOrganization(teamId, 25L, 0L);
// deletions.projects[]: { projectId, name, teamId, deletionStatus, deletedAt, purgeAt, ... }
// Owner 明确指定单个项目(不要自动选列表首个),重新读取确认仍为 pending_purge 后恢复
var restored = projects.restoreDeletionByOrganization(teamId, "<projectId>");
// 成功返回 { status: 'restored', projectId, requestId };409 表示状态已变化,重新查询不要重试deletions = projects.list_deletions_by_organization(team_id=team_id, limit=25, offset=0)
# deletions.projects[]: { projectId, name, teamId, deletionStatus, deletedAt, purgeAt, ... }
# Owner 明确指定单个项目(不要自动选列表首个),重新读取确认仍为 pending_purge 后恢复
restored = projects.restore_deletion_by_organization(team_id=team_id, project_id='<projectId>')
# 成功返回 { status: 'restored', projectId, requestId };409 表示状态已变化,重新查询不要重试deletions, err := projects.ListDeletionsByOrganization(teamId,
projects.WithListDeletionsByOrganizationLimit(25),
projects.WithListDeletionsByOrganizationOffset(0))
// deletions.Projects[]: { ProjectId, Name, TeamId, DeletionStatus, DeletedAt, PurgeAt, ... }
// Owner 明确指定单个项目(不要自动选列表首个),重新读取确认仍为 pending_purge 后恢复
restored, err := projects.RestoreDeletionByOrganization(teamId, "<projectId>")
// 成功返回 { Status: "restored", ProjectId, RequestId };409 表示状态已变化,重新查询不要重试# 查询删除生命周期(deletedAt 倒序)
curl -sS --get "$APPBASE_ENDPOINT/teams/$APPBASE_ORGANIZATION_TEAM_ID/projects/deletions" \
-H 'X-Appwrite-Project: console' \
-H "X-Appwrite-JWT: $APPBASE_OWNER_JWT" \
-H "X-Appwrite-Organization: $APPBASE_ORGANIZATION_TEAM_ID" \
--data-urlencode 'limit=25' \
--data-urlencode 'offset=0'
# 恢复:确认仍为 pending_purge 后,Owner 指定单个项目
curl -sS -X DELETE "$APPBASE_ENDPOINT/teams/$APPBASE_ORGANIZATION_TEAM_ID/projects/$APPBASE_PROJECT_ID_TO_RESTORE/deletion" \
-H 'X-Appwrite-Project: console' \
-H "X-Appwrite-JWT: $APPBASE_OWNER_JWT" \
-H "X-Appwrite-Organization: $APPBASE_ORGANIZATION_TEAM_ID"示例指引
- 各语言写法集中在语言树
examples/;分页循环、dry run→确认→提交、恢复前状态复核的完整代码序列见skills/ob-agentbase/references/project-inactivity-cleanup.md。
事实源
skills/ob-agentbase/references/project-inactivity-cleanup.mdskills/ob-agentbase/references/release-2.6.0.md(安全默认值与项目删除门禁)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(Web/Node/Java
Projectsservice 四方法签名与路径)