166af50219
- Moved bttoxin_digger_v5_repro to tools/reproduction/bttoxin_digger - Updated docker-compose.yml to point to the new location - This declutters the root directory while preserving the reproduction environment
207 lines
5.5 KiB
Markdown
207 lines
5.5 KiB
Markdown
# BtToxin_Digger v5 Reproduction - AGENTS.md
|
||
|
||
本文档为 AI 助手和开发者提供 bttoxin_digger_v5_repro 项目的快速参考指南。
|
||
|
||
## 项目概述
|
||
|
||
BtToxin_Digger v5 Reproduction 是一个基于 Pixi 和 Docker 的 BtToxin_Digger 1.0.10 可复现运行环境，集成了最新的 BLAST v5 毒素数据库。
|
||
|
||
**核心功能：**
|
||
- 使用 `ghcr.io/prefix-dev/pixi:latest` 作为基础镜像
|
||
- 预装 BtToxin_Digger 1.0.10 和 BLAST+ 2.16.0
|
||
- 内置最新版本的 BtToxin 数据库（20251104）
|
||
- 支持 Docker 容器化部署
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
bttoxin_digger_v5_repro/
|
||
├── docker/
|
||
│ └── Dockerfile # Docker 镜像构建文件
|
||
├── docker-compose.yml # 本地测试编排配置
|
||
├── external_dbs/ # 外部数据库源（构建时复制到镜像）
|
||
│ └── bt_toxin/
|
||
│ ├── db/ # BLAST 索引文件 (.phr, .pin, .psq)
|
||
│ │ ├── bt_toxin.pdb # 数据库元数据
|
||
│ │ ├── bt_toxin.phr # 蛋白质序列头索引
|
||
│ │ ├── bt_toxin.pin # 蛋白质序列索引
|
||
│ │ ├── bt_toxin.psq # 蛋白质序列数据
|
||
│ │ └── old/ # 历史索引备份
|
||
│ └── seq/ # FASTA 序列源文件
|
||
│ ├── bt_toxin20251104.fas # 最新毒素序列（2025年11月）
|
||
│ ├── bt_toxin20221208.fas
|
||
│ └── updateDB.py # 数据库辅助脚本
|
||
├── pixi.toml # Pixi 环境依赖定义
|
||
├── pixi.lock # 依赖版本锁定文件
|
||
├── examples/ # 测试用例
|
||
│ └── inputs/ # 输入文件
|
||
│ └── C15.fna # 测试基因组文件
|
||
└── README.md # 项目说明文档
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 构建 Docker 镜像
|
||
|
||
```bash
|
||
cd bttoxin_digger_v5_repro
|
||
docker compose build
|
||
```
|
||
|
||
### 运行分析（本地测试）
|
||
|
||
```bash
|
||
# 查看帮助
|
||
docker compose run --rm digger-repro pixi run BtToxin_Digger --help
|
||
|
||
# 运行分析
|
||
docker compose run --rm digger-repro pixi run BtToxin_Digger \
|
||
--SeqPath /app/jobs \
|
||
--Scaf_suffix .fna \
|
||
--threads 4
|
||
```
|
||
|
||
### 使用主服务中的 Digger 容器
|
||
|
||
主项目的 `docker/docker-compose.yml` 中包含一个持久运行的 `digger` 服务：
|
||
|
||
```bash
|
||
# 检查服务状态
|
||
docker ps | grep bttoxin_digger
|
||
|
||
# 执行分析任务
|
||
docker exec bttoxin_digger pixi run BtToxin_Digger \
|
||
--SeqPath /data \
|
||
--Scaf_suffix .fna \
|
||
--threads 4
|
||
```
|
||
|
||
## 数据库管理
|
||
|
||
### 数据库结构说明
|
||
|
||
- **`seq/` 目录**：存放原始 FASTA 序列文件（如 `bt_toxin20251104.fas`）
|
||
- **`db/` 目录**：存放 BLAST 生成的二进制索引文件
|
||
- **对应关系**：`db/` 中的文件由 `makeblastdb` 命令从 `seq/` 中的 FASTA 文件生成
|
||
|
||
### 验证数据库版本
|
||
|
||
```bash
|
||
docker exec bttoxin_digger pixi run blastdbcmd \
|
||
-db /app/.pixi/envs/default/bin/BTTCMP_db/bt_toxin/db/bt_toxin \
|
||
-info
|
||
```
|
||
|
||
**预期输出：**
|
||
```text
|
||
Database: bt_toxin20251104.fas
|
||
Date: Nov 4, 2025 3:35 PM
|
||
BLASTDB Version: 5
|
||
```
|
||
|
||
### 更新数据库（未来版本）
|
||
|
||
当上游仓库发布新版本（如 2026/2027 年）时：
|
||
|
||
```bash
|
||
# 1. 下载新序列文件到 seq/ 目录
|
||
cp /path/to/new/bt_toxin20xxxxxx.fas external_dbs/bt_toxin/seq/
|
||
|
||
# 2. 重新生成索引（使用 makeblastdb）
|
||
makeblastdb \
|
||
-in external_dbs/bt_toxin/seq/bt_toxin20xxxxxx.fas \
|
||
-dbtype prot \
|
||
-out external_dbs/bt_toxin/db/bt_toxin \
|
||
-parse_seqids
|
||
|
||
# 3. 重新构建 Docker 镜像
|
||
docker compose build --no-cache
|
||
|
||
# 4. 重启服务
|
||
docker compose -f ../docker/docker-compose.yml up -d digger
|
||
```
|
||
|
||
## 常见任务
|
||
|
||
### 查看 Digger 帮助
|
||
|
||
```bash
|
||
docker exec bttoxin_digger pixi run BtToxin_Digger --help
|
||
```
|
||
|
||
### 重新构建镜像（无缓存）
|
||
|
||
```bash
|
||
cd bttoxin_digger_v5_repro
|
||
docker compose build --no-cache
|
||
```
|
||
|
||
### 查看容器日志
|
||
|
||
```bash
|
||
docker logs bttoxin_digger
|
||
```
|
||
|
||
### 进入容器交互模式
|
||
|
||
```bash
|
||
docker exec -it bttoxin_digger pixi run bash
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 问题：数据库版本不正确
|
||
|
||
**症状**：分析结果显示使用的是旧版本数据库。
|
||
|
||
**排查步骤：**
|
||
1. 检查 `external_dbs/bt_toxin/seq/` 目录下的文件是否为最新
|
||
2. 确认 `external_dbs/bt_toxin/db/` 目录下的索引文件与 seq 文件匹配
|
||
3. 验证镜像已重建：`docker images | grep digger`
|
||
4. 重启服务：`docker compose -f ../docker/docker-compose.yml up -d digger`
|
||
|
||
### 问题：Perl 警告
|
||
|
||
**症状**：`Possible precedence issue with control flow operator`
|
||
|
||
**说明**：这是 Perl 5.26 与旧代码的兼容性问题，不影响程序运行，可忽略。
|
||
|
||
### 问题：容器启动失败
|
||
|
||
**排查步骤：**
|
||
1. 检查 Docker 是否运行
|
||
2. 查看详细日志：`docker compose logs`
|
||
3. 确认端口未被占用
|
||
|
||
## 开发说明
|
||
|
||
### 修改 Dockerfile
|
||
|
||
如需修改环境依赖：
|
||
1. 编辑 `pixi.toml`（添加/删除依赖）
|
||
2. 运行 `pixi lock` 更新 `pixi.lock`
|
||
3. 重新构建镜像
|
||
|
||
### 本地开发模式（不使用 Docker）
|
||
|
||
```bash
|
||
# 安装 Pixi 环境
|
||
cd bttoxin_digger_v5_repro
|
||
pixi install
|
||
|
||
# 链接外部数据库
|
||
ENV_BIN=.pixi/envs/default/bin
|
||
rm -rf "$ENV_BIN/BTTCMP_db/bt_toxin"
|
||
ln -sfn $(pwd)/external_dbs/bt_toxin "$ENV_BIN/BTTCMP_db/bt_toxin"
|
||
|
||
# 运行
|
||
pixi run BtToxin_Digger --help
|
||
```
|
||
|
||
## 相关文件
|
||
|
||
- `README.md`：项目完整说明（英文）
|
||
- `README_CN.md`：项目完整说明（中文）
|
||
- `docker/Dockerfile`：Docker 镜像构建配置
|
||
- `docker-compose.yml`：本地测试编排配置
|