OMERO 高级集成安全指南权限模型、Fileset 原始数据、破坏性操作与 OMERO.web 公开 API 边界【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本篇技术指南围绕scientific-agent-skills仓库中 OMERO 集成技能omero-integration的进阶参考文档展开系统讲解 OMERO.server 中会扩大查询范围、暴露原始数据或修改服务器状态的高级操作组权限判定、跨组与代用户操作、Fileset 与原始文件下载、删除等破坏性命令、所有权/组变更、HQL 查询安全、已废弃服务、OMERO.web 公开 API 边界以及公开数据发布。读完本文你将掌握一套先检查、再授权、后执行的高风险操作守则能够安全地对 OMERO.server 执行有界的原文件下载、受控删除、所有权变更与 JSON API 集成并避免把webclient内部路由误当作稳定接口。本文事实基础为 advanced.md并辅以该技能仓库中的 SKILL.md、connection.md、data_access.md、rois.md、scripts.md、sources.md 以及scripts/下的实际实现与测试。操作前提OMERO 数据可能包含未发表图像、标识符、注释、原始文件与派生测量值。任何远程操作之前请先阅读 SKILL.md 中的 Operating Contract运行契约并确认服务器版本与omero-py的兼容配对技能快照 2026-07-23 使用 OMERO.server 5.6.18 与omero-py5.22.1。组权限模型权限字符串是策略声明不是操作许可OMERO 的组权限通常用六字符权限字符串表示常见的四种策略为权限名称权限字符串含义privaterw----仅组成员可读写自己的对象read-onlyrwr---组成员可读他人对象但不能修改read-annotaterwra--组成员可读并为他人对象添加注释read-writerwrw--组成员可读写组内所有对象关键认知该字符串描述的是组策略group policy而非对某次具体操作的许可保证。一次操作是否真正被允许还取决于对象所有权、管理员权限、对象状态如是否被锁定以及链接规则link rules。因此不要凭组权限字符串推断自己能做什么而应当通过 API 现场检查inspect, do not infer。对单个对象做权限检查的标准模式如下源自 advanced.mdimage conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) details image.getDetails() permissions details.getPermissions() print( { group_id: details.getGroup().getId(), owner_id: details.getOwner().getId(), can_edit: permissions.canEdit(), can_annotate: permissions.canAnnotate(), can_link: permissions.canLink(), can_delete: permissions.canDelete(), } )输出时遵循最小暴露原则除非确实需要不要打印 owner/group 名称或邮箱地址。这一点与仓库中 inventory.py 的实现一致——其object_record()只序列化owner_id与group_id名称默认以name_redacted: True标记test_scripts.py 中的InventoryTests.test_inventory_pages_and_redacts_names专门验证了关闭--include-names时序列化结果中不出现任何sensitive内容。组上下文显式单组优先-1是高风险开关连接后的默认组来自会话事件上下文conn.getEventContext().groupId。进行有界查询前应当显式设定一个可访问组group_id 42 conn.SERVICE_OPTS.setOmeroGroup(str(group_id))而conn.SERVICE_OPTS.setOmeroGroup(-1)表示请求所有可访问组cross-group它可能将查询范围放大数倍暴露非当前任务协作意图的数据。使用-1必须满足三个条件见 advanced.md获得显式的跨组批准explicit cross-group approval设置总量上限total cap输出中标注组 ID保证可审计。同时参考 connection.md临时切换上下文后必须记录原组并在后续写入前恢复绝不能把-1当作对象找不到时的兜底方案。仓库配套的 inventory.py 在设计上彻底规避了这一风险——它的--group-id参数只接受正整数--help明确写着cross-group -1 is not supported并且输出的 scope 对象中始终包含cross_group: False。跨组与代用户操作suConn()与 CLI--sudo的严格边界suConn()BlitzGateway 的代用户连接与 CLI 的--sudo是特权冒充机制privileged impersonation只能用于管理员批准的任务。启用前必须逐项确认发起操作的管理员身份initiating administrator identity目标用户target user目标组target group精确的操作与对象 IDexact operation and IDs审计/日志预期audit/logging expectations替身连接使用后立即关闭immediate closure。红线规则绝不能仅仅为了绕过一个权限错误而创建替身连接。换句话说权限错误应当通过调整组上下文、确认对象归属或向管理员申请授权来解决而不是换一个身份硬闯。Filesets 与原始数据先看元数据再定下载范围Fileset 代表原始导入文件的集合original imported file collections。一个 Fileset 可能支撑多张图像并包含嵌套目录结构fileset image.getFileset() if fileset is not None: print(fileset.getId())原始文件的路径与文件名可能泄露采集布局acquisition layout或样本标识符因此不要在常规清点general inventory中枚举它们。这与 data_access.md 的指引一致下载Image或Fileset可能拉取多个原始文件及其目录结构必须事先估算规模。当前 CLIomero-py5.22.1支持下载四类显式对象omero download OriginalFile:123 ./reviewed-file omero download FileAnnotation:456 ./reviewed-file omero download Image:789 ./reviewed-empty-directory omero download Fileset:321 ./reviewed-empty-directory其中Image与Fileset可能展开为多个文件因此必须先检查文件数量与总大小使用专用目标目录dedicated destination做碰撞检测collision check与符号链接检查symlink check通过已提示的已存会话prompted stored session认证绝不在命令行追加-w/--password/-k密码或密钥参数。RawFileStore 直接读取必须设界并关闭对原始文件字节的直接访问走RawFileStore示例advanced.md如下max_bytes 50 * 1024 * 1024 store conn.createRawFileStore() try: store.setFileId(original_file_id) size store.size() if size max_bytes: raise ValueError(OriginalFile exceeds approved byte limit) chunk store.read(0, min(size, 1024 * 1024)) finally: store.close()该示例刻意只读取一个 chunk。完整下载需要循环读取 累计字节校验 调用方选择的本地安全路径。这也呼应了 connection.md 与 SKILL.md 运行契约中反复强调的原则状态型服务raw store、table handle、rendering engine 等都要在最短作用域内创建、使用、关闭且最终必须关闭BlitzGateway本身。值得注意的是仓库配套的 export_image_metadata.py 是不碰字节的典范它对 FileAnnotation 只输出original_file_id、size_bytes、mimetype与bytes_downloaded: False文件名默认脱敏除非显式传入--include-file-names脚本描述也写明了No pixels or attachment bytes are retrieved。破坏性命令删除delete的完整工作流conn.deleteObjects(type, ids, waitTrue)向服务器提交一条 OMERO 命令。它的具体影响取决于对象类型、链接、所有权与服务端图规则server graph rules——不要凭直觉承诺级联删除cascade或孤儿清理orphan的结果。文档要求的标准删除流程共八步在单个组内解析出显式的对象类型与 ID 集合读取当前对象/链接摘要与权限依据文档化查询展示计数与可能关联的对象就这些精确 ID获得显式批准以waitTrue提交或持续监控返回的命令回调command callback检查命令响应中的错误按 ID 记录成功/失败关闭回调/句柄以及 gateway。两条硬性禁令绝不通过宽泛的名称/命名空间查询来选择删除目标必须先做 ID 审查绝不在清点inventory或导出脚本中加入删除模式。另外要区分两种不同的图变更graph change解除链接unlink一个注释、表格、图像或数据集与删除delete子对象是两回事。执行前必须说清楚到底要做哪一个。仓库中的实现印证了这一原则inventory.py 与 export_image_metadata.py 都是严格只读的——执行模式仍以mode: executed-read-only标记输出而 plan_transfer.py 连--execute都没有永远停留在生成本地计划阶段。所有权与组变更影响面大必须走服务级 API改变所有权或在组间移动数据可能改变大量关联对象的访问权限。当前 CLI 文档说明所有权变更需要完全管理员full admin、具备相应权限的受限管理员restricted admin或组所有者group owner。变更前必须枚举精确的根对象与受影响的链接确认源组与目标组确认目标所有者的组成员关系检查 filesets/annotations/tables 是否会随对象图一起移动获得管理员批准使用当前文档化的 CLI/API 方法。明确禁止直接操作私有模型字段如旧示例中的_obj.details.owner赋值来绕过服务级策略service-level policy。写私有字段绕过策略在任何情况下都不应成为实现手段。HQL 与查询服务固定模板 类型化参数查询服务Query Service的用法要求固定 HQL 与类型化参数import omero.sys parameters omero.sys.ParametersI() parameters.addLong(image_id, image_id) query select i from Image i where i.id :image_id model_image conn.getQueryService().findByQuery(query, parameters)安全规则绝不把名称、命名空间、ID、排序方式或任意用户文本插值interpolate进 HQL用户的选择必须映射到白名单化的固定查询模板allowlisted fixed query templates列表查询必须施加服务端结果上限server-side result limit。这与 scripts.md 中 OMERO.server 脚本的安全要求一脉相承不使用eval()/exec()处理参数不把参数文本插值进 HQL、文件系统路径、命令或表条件。已废弃的服务面IRoi与IShare当前生成的 API 至少将以下接口标记为废弃deprecatedIRoiIShare对IRoi的务实态度rois.md 提供了更完整的展开当前官方 Python 示例仍在用roi_service.findByImage(image_id, None)读取 ROI因此该用法仍可用但面临移除风险at removal risk而非已经移除。正确做法是把IRoi的调用隔离在小型函数内不要围绕遗留的测量表格助手构建新的宽泛工作流依赖它之前先核验目标服务器的生成 API在长期集成中记录该依赖。对于IShare不要基于它构建新的共享工作流应改用当前管理员支持的 OMERO.web / 公开数据public-data特性。废弃不等于立即移除但它意味着调用方不能声称长期稳定也不能凭空发明替代方案。仓库中的 export_image_metadata.py 是隔离 记录的范例它使用connection.getRoiService()与findByImage但在输出 JSON 的api_notes中明确写入两条说明——IRoi.findByImage is used by current official Python examples but IRoi is deprecated以及ROI limits bound serialization; findByImage itself does not expose pagination。测试 test_scripts.py 中RedactionTests进一步验证了脱敏行为。OMERO.web只有api与webgateway是稳定公开 API官方 OMERO.web 开发者文档明确只有api与webgateway两个内置应用是稳定公开 API。其他应用包括webclient暴露的是内部 URL 与方法可能在次要版本中变化。UI 当前正在使用的某个 URL并不自动等于受支持的集成端点。JSON APIapi应用文档化的 OMERO JSON API 具备以下特性advanced.md由api这个 Django 应用实现在GET /api/通告支持的主版本在GET /api/v0/通告起始 URL在响应头X-OMERO-ApiVersion报告完整 API 版本使用limit与offset分页报告totalCount、limit、offset与服务器maxLimitPOST/PUT/DELETE 需要 CSRF token登录方式文档化于/api/v0/login/支持文档化模型类型的读端点包括 ROI 列表当前仅将对象创建/更新限制在 Project、Dataset、Screen 三种类型。官方文档虽然描述了 create/read/update/delete 访问但也明确限制了类型覆盖。因此不要称其为完整的通用 REST 接口不要假定 OAuth、不要假定 token 认证不要臆测服务器发现响应中未列出的端点。安全要点使用 HTTPSJSON API 密码通过文档化的登录 POST 发送绝不能记入日志遵循服务器返回的maxLimit客户端再施加更小的上限。ROI 列表端点为/api/v0/m/rois/?imageidlimitnoffsetn见 rois.md且仅在站点以 HTTPS 暴露文档化api应用且认证模型合适时才使用。WebGatewaywebgateway提供文档化的渲染图像与 JSON 数据。使用前确认当前端点页面endpoint page、限制图像大小/质量、使用 HTTPS。不要用 webclient 的 AJAX 路由替代它。公开数据与链接发布是管理员配置不是客户端操作把数据公开是管理员配置不是客户端一句make public的 API 调用。当前官方指引advanced.md 与 sources.md 均有依据创建一个专用的只读组dedicated read-only group创建/添加一个只拥有预期数据访问权限的公开用户public useromero.web.public.enabled默认false公开用户默认只读GET-onlyomero.web.public.url_filter必须显式放行路由否则不匹配任何内容下载/导出路由可以被排除在外专门的公开 OMERO.web 部署可能是合适的方案。OME 官方示例中确实使用webclient/?showproject-...这类链接做发布导航但 webclient 本身明确不是稳定公开 API——不要承诺此类链接是永久集成契约。对于持久化的发布 URL应使用管理员管理的重定向/DOI并在升级后重新测试。绝不因为当前登录用户可读就生成公开链接。发布前逐项确认公开用户是否已启用其组成员关系是否允许访问该对象GET-only 是否仍然开启URL filter 是否只放行预期路由下载/导出路由是刻意放行还是刻意阻断机构是否批准公开发布。OMERO CLI 的 Import/Admin 边界OMERODIR与服务器树安装omero-py会带来 CLI 框架但import/admin 命令还依赖一个兼容的、解压后的 OMERO.server 目录树通过OMERODIR提供。要点不要把OMERODIR指向任意的、版本不匹配的服务器发行版普通远程 BlitzGateway 客户端不需要该服务器树远程客户端命令与本地服务器管理具有不同风险等级执行任何 admin 命令前确认它正运行在预期的宿主机与预期的服务器安装/配置上。配套的安装建议SKILL.md 与 connection.md在 Python 3.12 隔离环境中安装与解释器/OS/架构匹配的zeroc_ice-3.6.5wheelOMERO 5.6 推荐 Ice 3.6Ice 3.7 不受支持再安装omero-py5.22.1uv venv --python 3.12 .venv source .venv/bin/activate uv pip install /absolute/path/to/zeroc_ice-3.6.5-matching-tags.whl uv pip install omero-py5.22.1wheel 标签必须同时匹配 CPython 版本cp310/cp311/cp312、操作系统、架构与平台兼容标签若 wheel 被拒不要静默回退去编译 IcePy先检查解释器与平台。仓库配套只读助手如何落地有界 脱敏 干跑omero-integration技能在scripts/下内置了一组本地安全助手它们是上述高级操作守则在代码层面的具象化详见 scripts.mdpython -B scripts/validate_config.py --help python -B scripts/inventory.py --help python -B scripts/export_image_metadata.py --help python -B scripts/plan_transfer.py --help所有助手共享同一套安全模型omero_common.py 实现只读取 frontmatter 中列出的OMERO_*命名变量绝不加载.env远程助手默认干跑dry-run需要--execute才连接且--execute只授权只读连接不授权更广范围或变更强制硬上限如 inventory 总上限 1000、页上限 200拒绝输出碰撞/符号链接连接与输出路径均做校验load_connection_config拒绝带 URL scheme 的主机名、拒绝半套用户名/密码、当存在OMERO_SESSION_KEY时自动忽略陈旧密码变量且从不外泄凭据gateway_session上下文管理器在finally中关闭连接异常信息经scrubbed_error清洗绝不打印凭据值JSON 输出原子写入且权限为 0600禁止覆写除非--overwrite拒绝符号链接目标。test_scripts.py 用假对象FakeConnection、FakeAnnotation 等在无服务器环境下验证了这些契约分页偏移[0, 2, 4]、名称脱敏、凭据不出现在序列化结果、导入计划不含任何凭据标志、导出计划能检测文件碰撞。运行本地测试无需真实服务器PYTHONDONTWRITEBYTECODE1 \ python -B -m unittest discover \ -s tests/omero-integration \ -p test_*.py高级操作总检查清单结束前逐项核对该清单源自 advanced.md 的 Advanced Operation Checklist已核验当前服务器/客户端/API 文档已确认精确的用户、组、对象类型与 ID跨组/冒充操作已单独授权权限检查不能替代授权permission checks do not replace authorization已审查原始文件数量/字节数与目标目录使用带类型化参数的固定查询废弃服务已隔离并记录只把api/webgateway当作稳定 OMERO.web API公开访问由管理员配置而非推断破坏性命令已预览、确认、监控并记录每个状态型服务/回调/连接都已关闭按照以上流程你就可以在 OMERO 集成中把扩大范围、暴露原始数据、变更服务器状态的高风险操作收敛为可审计、可回滚、有边界的工程实践。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OMERO 高级集成安全指南：权限模型、Fileset 原始数据、破坏性操作与 OMERO.web 公开 API 边界
OMERO 高级集成安全指南权限模型、Fileset 原始数据、破坏性操作与 OMERO.web 公开 API 边界【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本篇技术指南围绕scientific-agent-skills仓库中 OMERO 集成技能omero-integration的进阶参考文档展开系统讲解 OMERO.server 中会扩大查询范围、暴露原始数据或修改服务器状态的高级操作组权限判定、跨组与代用户操作、Fileset 与原始文件下载、删除等破坏性命令、所有权/组变更、HQL 查询安全、已废弃服务、OMERO.web 公开 API 边界以及公开数据发布。读完本文你将掌握一套先检查、再授权、后执行的高风险操作守则能够安全地对 OMERO.server 执行有界的原文件下载、受控删除、所有权变更与 JSON API 集成并避免把webclient内部路由误当作稳定接口。本文事实基础为 advanced.md并辅以该技能仓库中的 SKILL.md、connection.md、data_access.md、rois.md、scripts.md、sources.md 以及scripts/下的实际实现与测试。操作前提OMERO 数据可能包含未发表图像、标识符、注释、原始文件与派生测量值。任何远程操作之前请先阅读 SKILL.md 中的 Operating Contract运行契约并确认服务器版本与omero-py的兼容配对技能快照 2026-07-23 使用 OMERO.server 5.6.18 与omero-py5.22.1。组权限模型权限字符串是策略声明不是操作许可OMERO 的组权限通常用六字符权限字符串表示常见的四种策略为权限名称权限字符串含义privaterw----仅组成员可读写自己的对象read-onlyrwr---组成员可读他人对象但不能修改read-annotaterwra--组成员可读并为他人对象添加注释read-writerwrw--组成员可读写组内所有对象关键认知该字符串描述的是组策略group policy而非对某次具体操作的许可保证。一次操作是否真正被允许还取决于对象所有权、管理员权限、对象状态如是否被锁定以及链接规则link rules。因此不要凭组权限字符串推断自己能做什么而应当通过 API 现场检查inspect, do not infer。对单个对象做权限检查的标准模式如下源自 advanced.mdimage conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) details image.getDetails() permissions details.getPermissions() print( { group_id: details.getGroup().getId(), owner_id: details.getOwner().getId(), can_edit: permissions.canEdit(), can_annotate: permissions.canAnnotate(), can_link: permissions.canLink(), can_delete: permissions.canDelete(), } )输出时遵循最小暴露原则除非确实需要不要打印 owner/group 名称或邮箱地址。这一点与仓库中 inventory.py 的实现一致——其object_record()只序列化owner_id与group_id名称默认以name_redacted: True标记test_scripts.py 中的InventoryTests.test_inventory_pages_and_redacts_names专门验证了关闭--include-names时序列化结果中不出现任何sensitive内容。组上下文显式单组优先-1是高风险开关连接后的默认组来自会话事件上下文conn.getEventContext().groupId。进行有界查询前应当显式设定一个可访问组group_id 42 conn.SERVICE_OPTS.setOmeroGroup(str(group_id))而conn.SERVICE_OPTS.setOmeroGroup(-1)表示请求所有可访问组cross-group它可能将查询范围放大数倍暴露非当前任务协作意图的数据。使用-1必须满足三个条件见 advanced.md获得显式的跨组批准explicit cross-group approval设置总量上限total cap输出中标注组 ID保证可审计。同时参考 connection.md临时切换上下文后必须记录原组并在后续写入前恢复绝不能把-1当作对象找不到时的兜底方案。仓库配套的 inventory.py 在设计上彻底规避了这一风险——它的--group-id参数只接受正整数--help明确写着cross-group -1 is not supported并且输出的 scope 对象中始终包含cross_group: False。跨组与代用户操作suConn()与 CLI--sudo的严格边界suConn()BlitzGateway 的代用户连接与 CLI 的--sudo是特权冒充机制privileged impersonation只能用于管理员批准的任务。启用前必须逐项确认发起操作的管理员身份initiating administrator identity目标用户target user目标组target group精确的操作与对象 IDexact operation and IDs审计/日志预期audit/logging expectations替身连接使用后立即关闭immediate closure。红线规则绝不能仅仅为了绕过一个权限错误而创建替身连接。换句话说权限错误应当通过调整组上下文、确认对象归属或向管理员申请授权来解决而不是换一个身份硬闯。Filesets 与原始数据先看元数据再定下载范围Fileset 代表原始导入文件的集合original imported file collections。一个 Fileset 可能支撑多张图像并包含嵌套目录结构fileset image.getFileset() if fileset is not None: print(fileset.getId())原始文件的路径与文件名可能泄露采集布局acquisition layout或样本标识符因此不要在常规清点general inventory中枚举它们。这与 data_access.md 的指引一致下载Image或Fileset可能拉取多个原始文件及其目录结构必须事先估算规模。当前 CLIomero-py5.22.1支持下载四类显式对象omero download OriginalFile:123 ./reviewed-file omero download FileAnnotation:456 ./reviewed-file omero download Image:789 ./reviewed-empty-directory omero download Fileset:321 ./reviewed-empty-directory其中Image与Fileset可能展开为多个文件因此必须先检查文件数量与总大小使用专用目标目录dedicated destination做碰撞检测collision check与符号链接检查symlink check通过已提示的已存会话prompted stored session认证绝不在命令行追加-w/--password/-k密码或密钥参数。RawFileStore 直接读取必须设界并关闭对原始文件字节的直接访问走RawFileStore示例advanced.md如下max_bytes 50 * 1024 * 1024 store conn.createRawFileStore() try: store.setFileId(original_file_id) size store.size() if size max_bytes: raise ValueError(OriginalFile exceeds approved byte limit) chunk store.read(0, min(size, 1024 * 1024)) finally: store.close()该示例刻意只读取一个 chunk。完整下载需要循环读取 累计字节校验 调用方选择的本地安全路径。这也呼应了 connection.md 与 SKILL.md 运行契约中反复强调的原则状态型服务raw store、table handle、rendering engine 等都要在最短作用域内创建、使用、关闭且最终必须关闭BlitzGateway本身。值得注意的是仓库配套的 export_image_metadata.py 是不碰字节的典范它对 FileAnnotation 只输出original_file_id、size_bytes、mimetype与bytes_downloaded: False文件名默认脱敏除非显式传入--include-file-names脚本描述也写明了No pixels or attachment bytes are retrieved。破坏性命令删除delete的完整工作流conn.deleteObjects(type, ids, waitTrue)向服务器提交一条 OMERO 命令。它的具体影响取决于对象类型、链接、所有权与服务端图规则server graph rules——不要凭直觉承诺级联删除cascade或孤儿清理orphan的结果。文档要求的标准删除流程共八步在单个组内解析出显式的对象类型与 ID 集合读取当前对象/链接摘要与权限依据文档化查询展示计数与可能关联的对象就这些精确 ID获得显式批准以waitTrue提交或持续监控返回的命令回调command callback检查命令响应中的错误按 ID 记录成功/失败关闭回调/句柄以及 gateway。两条硬性禁令绝不通过宽泛的名称/命名空间查询来选择删除目标必须先做 ID 审查绝不在清点inventory或导出脚本中加入删除模式。另外要区分两种不同的图变更graph change解除链接unlink一个注释、表格、图像或数据集与删除delete子对象是两回事。执行前必须说清楚到底要做哪一个。仓库中的实现印证了这一原则inventory.py 与 export_image_metadata.py 都是严格只读的——执行模式仍以mode: executed-read-only标记输出而 plan_transfer.py 连--execute都没有永远停留在生成本地计划阶段。所有权与组变更影响面大必须走服务级 API改变所有权或在组间移动数据可能改变大量关联对象的访问权限。当前 CLI 文档说明所有权变更需要完全管理员full admin、具备相应权限的受限管理员restricted admin或组所有者group owner。变更前必须枚举精确的根对象与受影响的链接确认源组与目标组确认目标所有者的组成员关系检查 filesets/annotations/tables 是否会随对象图一起移动获得管理员批准使用当前文档化的 CLI/API 方法。明确禁止直接操作私有模型字段如旧示例中的_obj.details.owner赋值来绕过服务级策略service-level policy。写私有字段绕过策略在任何情况下都不应成为实现手段。HQL 与查询服务固定模板 类型化参数查询服务Query Service的用法要求固定 HQL 与类型化参数import omero.sys parameters omero.sys.ParametersI() parameters.addLong(image_id, image_id) query select i from Image i where i.id :image_id model_image conn.getQueryService().findByQuery(query, parameters)安全规则绝不把名称、命名空间、ID、排序方式或任意用户文本插值interpolate进 HQL用户的选择必须映射到白名单化的固定查询模板allowlisted fixed query templates列表查询必须施加服务端结果上限server-side result limit。这与 scripts.md 中 OMERO.server 脚本的安全要求一脉相承不使用eval()/exec()处理参数不把参数文本插值进 HQL、文件系统路径、命令或表条件。已废弃的服务面IRoi与IShare当前生成的 API 至少将以下接口标记为废弃deprecatedIRoiIShare对IRoi的务实态度rois.md 提供了更完整的展开当前官方 Python 示例仍在用roi_service.findByImage(image_id, None)读取 ROI因此该用法仍可用但面临移除风险at removal risk而非已经移除。正确做法是把IRoi的调用隔离在小型函数内不要围绕遗留的测量表格助手构建新的宽泛工作流依赖它之前先核验目标服务器的生成 API在长期集成中记录该依赖。对于IShare不要基于它构建新的共享工作流应改用当前管理员支持的 OMERO.web / 公开数据public-data特性。废弃不等于立即移除但它意味着调用方不能声称长期稳定也不能凭空发明替代方案。仓库中的 export_image_metadata.py 是隔离 记录的范例它使用connection.getRoiService()与findByImage但在输出 JSON 的api_notes中明确写入两条说明——IRoi.findByImage is used by current official Python examples but IRoi is deprecated以及ROI limits bound serialization; findByImage itself does not expose pagination。测试 test_scripts.py 中RedactionTests进一步验证了脱敏行为。OMERO.web只有api与webgateway是稳定公开 API官方 OMERO.web 开发者文档明确只有api与webgateway两个内置应用是稳定公开 API。其他应用包括webclient暴露的是内部 URL 与方法可能在次要版本中变化。UI 当前正在使用的某个 URL并不自动等于受支持的集成端点。JSON APIapi应用文档化的 OMERO JSON API 具备以下特性advanced.md由api这个 Django 应用实现在GET /api/通告支持的主版本在GET /api/v0/通告起始 URL在响应头X-OMERO-ApiVersion报告完整 API 版本使用limit与offset分页报告totalCount、limit、offset与服务器maxLimitPOST/PUT/DELETE 需要 CSRF token登录方式文档化于/api/v0/login/支持文档化模型类型的读端点包括 ROI 列表当前仅将对象创建/更新限制在 Project、Dataset、Screen 三种类型。官方文档虽然描述了 create/read/update/delete 访问但也明确限制了类型覆盖。因此不要称其为完整的通用 REST 接口不要假定 OAuth、不要假定 token 认证不要臆测服务器发现响应中未列出的端点。安全要点使用 HTTPSJSON API 密码通过文档化的登录 POST 发送绝不能记入日志遵循服务器返回的maxLimit客户端再施加更小的上限。ROI 列表端点为/api/v0/m/rois/?imageidlimitnoffsetn见 rois.md且仅在站点以 HTTPS 暴露文档化api应用且认证模型合适时才使用。WebGatewaywebgateway提供文档化的渲染图像与 JSON 数据。使用前确认当前端点页面endpoint page、限制图像大小/质量、使用 HTTPS。不要用 webclient 的 AJAX 路由替代它。公开数据与链接发布是管理员配置不是客户端操作把数据公开是管理员配置不是客户端一句make public的 API 调用。当前官方指引advanced.md 与 sources.md 均有依据创建一个专用的只读组dedicated read-only group创建/添加一个只拥有预期数据访问权限的公开用户public useromero.web.public.enabled默认false公开用户默认只读GET-onlyomero.web.public.url_filter必须显式放行路由否则不匹配任何内容下载/导出路由可以被排除在外专门的公开 OMERO.web 部署可能是合适的方案。OME 官方示例中确实使用webclient/?showproject-...这类链接做发布导航但 webclient 本身明确不是稳定公开 API——不要承诺此类链接是永久集成契约。对于持久化的发布 URL应使用管理员管理的重定向/DOI并在升级后重新测试。绝不因为当前登录用户可读就生成公开链接。发布前逐项确认公开用户是否已启用其组成员关系是否允许访问该对象GET-only 是否仍然开启URL filter 是否只放行预期路由下载/导出路由是刻意放行还是刻意阻断机构是否批准公开发布。OMERO CLI 的 Import/Admin 边界OMERODIR与服务器树安装omero-py会带来 CLI 框架但import/admin 命令还依赖一个兼容的、解压后的 OMERO.server 目录树通过OMERODIR提供。要点不要把OMERODIR指向任意的、版本不匹配的服务器发行版普通远程 BlitzGateway 客户端不需要该服务器树远程客户端命令与本地服务器管理具有不同风险等级执行任何 admin 命令前确认它正运行在预期的宿主机与预期的服务器安装/配置上。配套的安装建议SKILL.md 与 connection.md在 Python 3.12 隔离环境中安装与解释器/OS/架构匹配的zeroc_ice-3.6.5wheelOMERO 5.6 推荐 Ice 3.6Ice 3.7 不受支持再安装omero-py5.22.1uv venv --python 3.12 .venv source .venv/bin/activate uv pip install /absolute/path/to/zeroc_ice-3.6.5-matching-tags.whl uv pip install omero-py5.22.1wheel 标签必须同时匹配 CPython 版本cp310/cp311/cp312、操作系统、架构与平台兼容标签若 wheel 被拒不要静默回退去编译 IcePy先检查解释器与平台。仓库配套只读助手如何落地有界 脱敏 干跑omero-integration技能在scripts/下内置了一组本地安全助手它们是上述高级操作守则在代码层面的具象化详见 scripts.mdpython -B scripts/validate_config.py --help python -B scripts/inventory.py --help python -B scripts/export_image_metadata.py --help python -B scripts/plan_transfer.py --help所有助手共享同一套安全模型omero_common.py 实现只读取 frontmatter 中列出的OMERO_*命名变量绝不加载.env远程助手默认干跑dry-run需要--execute才连接且--execute只授权只读连接不授权更广范围或变更强制硬上限如 inventory 总上限 1000、页上限 200拒绝输出碰撞/符号链接连接与输出路径均做校验load_connection_config拒绝带 URL scheme 的主机名、拒绝半套用户名/密码、当存在OMERO_SESSION_KEY时自动忽略陈旧密码变量且从不外泄凭据gateway_session上下文管理器在finally中关闭连接异常信息经scrubbed_error清洗绝不打印凭据值JSON 输出原子写入且权限为 0600禁止覆写除非--overwrite拒绝符号链接目标。test_scripts.py 用假对象FakeConnection、FakeAnnotation 等在无服务器环境下验证了这些契约分页偏移[0, 2, 4]、名称脱敏、凭据不出现在序列化结果、导入计划不含任何凭据标志、导出计划能检测文件碰撞。运行本地测试无需真实服务器PYTHONDONTWRITEBYTECODE1 \ python -B -m unittest discover \ -s tests/omero-integration \ -p test_*.py高级操作总检查清单结束前逐项核对该清单源自 advanced.md 的 Advanced Operation Checklist已核验当前服务器/客户端/API 文档已确认精确的用户、组、对象类型与 ID跨组/冒充操作已单独授权权限检查不能替代授权permission checks do not replace authorization已审查原始文件数量/字节数与目标目录使用带类型化参数的固定查询废弃服务已隔离并记录只把api/webgateway当作稳定 OMERO.web API公开访问由管理员配置而非推断破坏性命令已预览、确认、监控并记录每个状态型服务/回调/连接都已关闭按照以上流程你就可以在 OMERO 集成中把扩大范围、暴露原始数据、变更服务器状态的高风险操作收敛为可审计、可回滚、有边界的工程实践。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考