annoexp

v0.1.4

Published

4 days ago

ProjectHub-backed single-cell exploration service and CLI

0High
0Medium
0Low

seqyuan

annoexp bioinformatics scRNA-seq single-cell h5ad projecthub cli

AnnoExp

AnnoExp 是一个面向 ProjectHub 的单细胞数据浏览与分析应用。

当前架构不是纯浏览器本地计算模式。后端负责读取 H5AD、执行 marker / expression / top marker dotplot / subcluster / cell annotation 等计算，通过 API 把结果返回给前端展示。

术语约定：本文档对外优先使用 projectId + datasetId。当前实现中的部分 HTTP 路由参数、CLI 参数和磁盘目录为了兼容仍保留 sampleId / samples / --sample 命名；可将它们视为当前代码层的 datasetId 兼容别名。

当前运行模式

后端：Node.js + Express + bakana
数据源：runtime home 下的 config/*.json 与 data/projecthub/*.h5ad
前端：React UI，请求 /api/projecthub/... 获取数据集输入与计算结果
持久化 annotation：默认写入独立 ProjectHub workspace（data/projecthub-workspace/），兼容读取旧 data/projecthub/.annotations/

更完整的后端接口、配置项和 ProjectHub 数据维护说明见 server/README.md。

快速开始

1. 开发环境安装依赖

npm install --legacy-peer-deps

2. 初始化 runtime

annoexp config

说明：

annoexp config 会交互式写入 runtime 配置
若当前 runtime 尚无管理员，会在向导末尾提示创建管理员
默认 runtime home 为 ~/.config/annoexp
若设置 ANNOEXP_HOME=/path/to/runtime，则改为使用该目录

3. 启动服务

annoexp serve

若在源码仓库内开发，也可以使用现有脚本：

npm run server

4. 启动前端开发环境

npm run start

同时启动后端和前端：

npm run start:full

开发时前端默认运行在 http://localhost:3000，/api 请求会代理到后端。

常用 CLI

annoexp config
annoexp config show
annoexp config path
annoexp serve
annoexp check
annoexp smoke projecthub
annoexp admin init --force
annoexp projecthub add --project PRJ001 --dataset dataset_a --path your_data.h5ad --write
annoexp projecthub sync --write
annoexp jwt generate

说明：

annoexp admin init：显式创建或重置管理员
annoexp projecthub add：精确追加一个项目/数据集，推荐使用 --dataset；旧 --sample 仍兼容
annoexp projecthub sync：扫描数据目录并生成/更新 config/projecthub.json
annoexp check：生产门禁检查

npm 发布形态

当前包的目标形态是：

安装后提供 annoexp CLI
annoexp serve 可直接启动后端
若包内存在前端构建产物，annoexp serve 也会同时托管内置前端页面

也就是说，对外发布时的主入口不是 npm run ...，而是安装后的 annoexp ...。

当前公开 npm 包名按 annoexp 收口，对应仓库是 seqyuan/annoexp。

发布后使用

客户安装时不需要源码仓库，也不需要 npm run ...。

全局安装：

npm install -g annoexp
annoexp config
annoexp serve

本地 tarball 试装：

npm pack
npm install -g ./annoexp-0.1.4.tgz
annoexp config
annoexp serve

发布前检查：

npm run release:check
npm run release:install-check
npm run publish:dry-run

完整发布前收口：

npm run release:full

说明：

release:check：检查包内容、runtime 构建产物、前端构建产物和禁止发布文件
release:install-check：真实执行 npm pack -> 干净目录安装 -> admin init -> projecthub add -> serve -> smoke
publish:dry-run：检查 npm publish 最终会带哪些文件

ProjectHub 数据更新

当前 ProjectHub 不是数据库驱动，主数据源仍是配置文件：

把新的 H5AD 放到 runtime home 的 data/projecthub/，或放到 PROJECTHUB_DATA_DIR 指向的目录
运行 annoexp projecthub add ... --write 追加单个数据集，或运行 annoexp projecthub sync --write 扫描批量纳管
保存后端索引后，服务端会自动清空 dataset cache
若 H5AD 文件内容变化，后端会按文件 mtime/size 自动使旧缓存失效

如果以后要切换成数据库，只需要替换 ProjectHub 索引读取与写入层，前后端 API 契约可以保持不变。

生产前最小检查

annoexp config
annoexp jwt generate
ANNOEXP_ADMIN_USERNAME=ops-admin ANNOEXP_ADMIN_PASSWORD='StrongAdminPass-2026' annoexp admin init --force
JWT_SECRET='<至少 32 字符的高熵密钥>' ANNOEXP_SINGLE_INSTANCE_ACK=true annoexp check

说明：

当前默认生产假设仍然是单实例、单写入者
本仓库当前不处理 Docker 部署收口

客户安装最小路径

下面这条是已经实际验证通过的最小安装路径：

npm install -g annoexp
export ANNOEXP_HOME=/data/annoexp
annoexp config
ANNOEXP_ADMIN_USERNAME=ops-admin ANNOEXP_ADMIN_PASSWORD='StrongAdminPass-2026' annoexp admin init --force
cp your_data.h5ad /data/annoexp/data/projecthub/
annoexp projecthub add --project PRJ001 --dataset dataset_a --path your_data.h5ad --write
JWT_SECRET='<至少 32 字符的高熵密钥>' annoexp serve

如需兼容旧脚本，也可以继续使用 --sample sample_a，效果等同于 --dataset dataset_a。

服务启动后可再执行：

BASE_URL=http://127.0.0.1:3001 \
ANNOEXP_SMOKE_USERNAME=ops-admin \
ANNOEXP_SMOKE_PASSWORD='StrongAdminPass-2026' \
annoexp smoke projecthub

开发备注

仓库里仍保留部分历史 annoc / browser-first 代码背景，但当前 annoexp 主路径是 ProjectHub 后端模式
在源码仓库目录内直接运行 npm run server、npm run check:prod 时，默认读取仓库根目录下的 config/ 与 data/
对外发布 CLI 时，推荐使用 annoexp ... 作为主入口，而不是 npm run ...