建树赶尾人一站式建树工具使用说明书

做一棵系统发育树，标准流程是「多序列比对 → 比对修剪 → 最大似然建树」三步，对应 MAFFT、trimAl、IQ-TREE 三套命令行软件。本页把这三步串成一条流水线：把测序文件拖进浏览器，点按钮（或一次「一键执行」），全部在服务器上跑完，结果直接在页面底部画出系统发育树 —— 不需要装软件，也不需要写命令。

对应页面：/build_tree（工具页左上角「? 功能说明书」即本页） · 序列会上传到服务器执行 MAFFT / trimAl / IQ-TREE

1这个页面解决什么问题

• 痛点：一套建树环境（MAFFT + trimAl + IQ-TREE）装下来动辄几百 MB，命令参数也各有各的写法；把三条命令手动串起来、还要在不同软件间倒文件，是菌物鉴定里最耗时的一环。
• 本页的做法：上传序列 → 对齐 → 裁切 → 建树，四步都在同一个页面里完成。每一步的中间结果（对齐后的峰图、裁切区、建出的树）都直接画在页面上，可看、可改、可下载。
• 支持的数据：.ab1（带四通道峰图，可目视判断质量、可手动裁切）、.seq / .fasta / .fa（纯文本序列）；也可以直接填 GenBank Accession ID 从 NCBI 拉取，或用 Excel / CSV 批量导入多位点（一个位点一列，导入后自动建标签页）。
• 多片段：ITS、tef1、rpb2… 不同片段各自放一个标签页（标签页名就是片段名，默认按 its → lsu → tef1 → rpb1 → rpb2 依次命名），独立跑流水线；建树时后端会把各片段拼成一条矩阵，并按自动生成的 NEXUS 分区文件让每个片段各用一套替换模型，一棵树同时用上全部片段（见第 7 节）。

2界面元素一览

页面右侧是一条固定的浮动操作栏，左侧是序列展示区。自上而下（绿色 = 常规的左键操作，红色 = 容易被忽略的隐藏入口）：

3四步流程

1. 1上传：点「+ 加载序列」选择文件（或直接拖入页面）。建树至少要 4 条序列，且应当是同源片段（例如都是同一条 ITS 引物扩出来的）。
2. 2对齐：点「🔗 Mafft对齐」。服务器跑 MAFFT，把长短不一的序列按同源位点排好，不足处在峰图上补出黄色虚线框的插入空位。
3. 3裁切：点「✂️ trimAl裁切」。自动识别因比对而变得不可靠的列（大片空位、两端乱序区），把它们灰化——灰块覆盖的列不参与建树。
4. 4建树：点「🌳 iqtree建树」。IQ-TREE 做最大似然建树 + UFBoot 自举检验，完成后页面底部直接画出系统发育树。

（第 2 至第 4 步也可以合并成一次「一键执行」。）三个执行按钮都还能 右键 / 长按 打开参数窗口，改完参数再跑，详见第 7 节。

4看懂「序列区块」

每个序列区块就是把一条测序读长摊开画出来。下面是同一条序列在加载后、与对齐后的样子（取同一段，便于对比）。

• 1四通道荧光曲线：G 黑、A 绿、T 红、C 蓝。纵轴为荧光强度，量程按四通道全局最大值动态缩放，保证所有峰顶都入画。
• 2整十位刻度线 + 顶部序号：每 10 个碱基一条灰线与序号，用于定位与报数。
• 3底部碱基行：机器判定出的碱基，字符颜色对应通道色，整行可连续复制。

（纯文本序列 .seq / .fasta 没有峰图数据，区块里只显示碱基行，没有四通道曲线。）

点「🔗 Mafft对齐」之后，同一段序列会变成：

• 1插入空位高亮框：MAFFT 为了让同源位点对齐而补进的位置。该位在本序列没有碱基（碱基行是黄色 -），但在别的序列上可能有——这正是「对齐」的含义。
• 2重新编号的对齐刻度：插入空位后，原有的「每 10 碱基」编号不再对得上，刻度会按对齐后的列号重算（图中同一段序列的刻度从 110/120… 顺移到 120/130…）。
• 3连续的插入空位会把后面的曲线整体推开：图中 140 刻度附近是一段连续空位，它右侧的峰形因此相对图 1 明显右移。 这样处理之后，曲线、碱基字符、刻度三者始终逐列对齐 —— 手动裁剪、修改碱基都依赖这个对齐关系。

换个样式看：峰图 / 紧凑 / 表格

标签页最左边的「样式」下拉决定序列怎么摆。三种样式读的是同一份数据，增删改在任何一种样式里做，切回来都对得上 —— 区别只在"摆法"和"能做的操作"。

图 3　「样式」下拉（展开）：峰图 / 紧凑 / 表格 下方一条是当前页统计

• 紧凑样式怎么读：顶部每 10 位一条竖线 + 序号，竖线画在第 10 个方块的右边界上、序号写在竖线左侧（对齐位置一眼能对上，不会读成第 9 位）。
• 紧凑里挪空位 / 改碱基 / 裁切：按住黄格（-）左右拖动就能把空位挪到别的位置（任何模式下都能拖），拖动时会有一条橙色虚线指示落点、源格高亮，松手即落位（每次只动这一行，不影响其它行）；开「✎ 修改碱基」后双击某个方块弹出 A/T/C/G/N 改碱基；进入「✂️ 手动裁切」后，从碱基格开始横拖即裁掉这一段列（只点一下不拖动不算裁切）。
  三者按按下的位置分工：落在黄格上是挪空位，落在碱基上是裁切（没进手动裁切时不动），所以「修改碱基」和「手动裁切」同时开着也不打架 —— 不必为挪空位先退出裁切。
• 对齐 / 裁切之后视图会自动跟上：不用手动重切样式，重建发生在同一批数据上。
• 表格里的同名：同一标本在各片段里名字相同时会自动排到同一行；同一片段里重名的会另起一行并按红字提示。
• 到底统计了什么：统计行里的「文件类型 峰图N/纯序列N」—— 峰图 = 带峰图的 .ab1，纯序列 = .seq / .fasta / 从 GenBank 下载的序列（二者在后续流程里完全等价）。

（这一步只影响"看"的方式，不参与计算：对齐、裁切、建树用的始终是同一批序列。）

5裁切：去掉不可靠的列

比对之后，两端和空位扎堆的区段会变得不可靠，直接拿去建树会引入噪声。trimAl 默认用 -automated1 自动判断，把这些列裁掉。 下面这张图取同一条序列的比对首端——那里裁切最集中、最容易看清：

• 1灰块（裁切掉的区域）：这些列会被排除在建树数据之外。灰块常落在比对的首尾或中段 —— 那些位置上序列普遍缺失、信号杂乱，trimAl 会把它们整段判为不可靠。 灰块内若同时出现黄色虚线框，说明该列既是插入空位、又被裁掉 —— 两种标记可以叠加。
• 2保留下来的碱基行：灰块右侧的列才真正送进 IQ-TREE。裁剪按列判定，所以除了连续的大段灰块，也可能出现零星的单列灰块。 若灰块占比过高，说明这段数据的可比对区段偏短，可考虑换一段更长的读长，或改用「手动裁剪」自己界定保留区。

手动裁剪

自动裁切有时过于激进或过保守，此时可以自己框选，两种入口：

• 裁切之前：右键（长按）「✂️ trimAl裁切」→ 在参数窗口点「手动裁剪」；
• 自动裁切之后：按钮已自动变成「✂️ 手动裁切」，直接点它即可进入手动裁剪模式。

然后在峰图上按住鼠标横向拖出一个框，松手即把该区间标记为裁切区（同样显示为灰块）。被手动裁剪的列同样不参与建树，但依然占列位。

6看懂「系统发育树」

建树成功后，页面底部会出现「🌳 系统发育树」区块 —— 这就是 IQ-TREE 的产出，直接画在页面上，无需跳转。

• 1节点置信度：枝端节点上方的红色数字，即 UFBoot 自举支持值（0–100）。越接近 100 越可靠；低于 70 的分支在解读时应当谨慎。
• 2比例尺：树图下方的比例尺给出枝长的尺度（默认 0.07，即图上一段 0.07 遗传距离有多长）。短枝不会被强制撑长，读树时以数字与相对长短为准。

树上方的控制条从左到右是：先在树上点选节点 → 点 重定根（以选中节点所在枝的中点作根）或 旋转（左右反转选中节点的子树顺序），改坏了点 ↺ 还原定根 就整棵树回到刚载入时的结构（重定根 / 旋转 / 排序一起撤销）；排序 是「复选框 + 下拉」一对控件 —— 勾上 按节点排序 才排序、后面下拉选「递增 / 递减」（按外部节点数即叶数排，默认勾上 + 递增，初始就已生效；取消勾选则按树文件里的原始顺序显示）；横向缩放 用右侧的拖动条（最左 = 0.1×，中间 0 位 = 1× 原样，最右 = 4×，只改横向）：往左把树体压窄、长枝的树也能一屏看全，往右拉宽后树图区下方会出现横向滚动条；最右是「🌲 去树查看器」，把当前树 POST 到树查看器页面（/viewTree），在功能完整的页面上继续分析。

名字很长时不会把树挤没：树体的宽度是按预设的名字长度算的，名字再长也只占右侧那一列； 画布会按真实名长自动加宽，比窗口宽时树图区底部出现横向滚动条，向右滚就能看全名字。 名字不长时画布与窗口同宽，不会出现滚动条。

这一块用的是与「树查看器」同一套 FigTree 引擎（viewtree_mini.js + 引擎的 figtree/ 解析·布局·渲染文件），但只保留了上表这几个功能；补间动画、撤销、极坐标/辐射布局、枝长变换、着色/高亮等都不在这里。

控制条上还有一个树文件下拉：一次建树会回传两份树，.treefile（最大似然树）与 .contree（一致树，由 1000 棵自举树合并而来）。下拉切换后，页面上画的树、以及「🔀 通过枝长重排序列」「🌲 去树查看器」「⬇ 下载 .treefile」「💾 下载本页」都会跟着换成选中的那一份，不会一个用 treefile、另一个用 contree。
命令里没带自举（-B）时不会产生 .contree，此时下拉只列出一项、不予显示。

7参数配置（右键 / 长按）

三个执行按钮都支持右键（手机上长按，或用「手机版右键」按钮）打开参数窗口。左键 = 按当前配置直接跑，右键 = 先改参数再跑。

参数窗口里显示的默认命令来自服务端配置，与真正会执行的命令同源，不会出现「窗口里显示一套、实际跑另一套」的漂移。

NEXUS 分区文件（多片段联合建树的关键）

建树窗口的下半部分是一个可以就地编辑的 NEXUS 分区文件，由页面按当前标签页自动生成，不需要你手写：

#nexus
begin sets;
  charset its = its.fasta: 1-650;
  charset lsu = lsu.fasta: 1-1200;
  charpartition mine = GTR+F+G4:its, GTR+F+I+G4:lsu;
end;

• charset 一行一个片段：名字 = 标签页名，后面的列区间由页面按该片段当前的实际列数自动算出来。
• charpartition 给每个片段指定替换模型。模型按片段类型（标签页名）给默认值：its → GTR+F+G4、lsu → GTR+F+I+G4、tef1 / rpb1 / rpb2 → GTR+F+G4；不在这五类里的名字统一用 GTR+F+G4 兜底。
  这些都只是「该位点的常规选择」，不是普适真理。想更数据驱动，可以把模型改成 MFP+MERGE 并把命令里的 -m 加回来，让 ModelFinder 逐分区自己挑（两者只能选一个，见上）。
• ⚠️ charpartition 要覆盖每一个 charset：漏掉的那个片段不会参与建树。页面生成时不会漏；你若手工删掉某个模型，记得自己补上。
• ⚠️ 列区间要与片段实际列数一致：后端在开跑前会做一次校验（各 charset 列数之和必须等于比对总列数），不一致会直接报错并停下来，不会带着错误的分区继续跑。
• 「↺ 恢复默认 nex 与命令」按钮把命令与分区文件一起回退到「按当前标签页自动生成」的样子，改坏了点它即可。

参数窗口里还可以勾选「🔗 所有标签页使用相同参数」（默认勾选）：取消后可为每个标签页分别指定命令，适合各片段用不同参数的场景。建树是一次跑一棵树，所有片段共用同一条命令；「片段级差异化」真正的落点在分区文件里的模型，以及 Mafft / trimAl 这两步（那两步本来就是每个标签页一个参数框）。

8工具箱

点「🧰 工具箱」弹出七项辅助功能（视图样式不在工具箱里：它是标签页最左边的「样式」下拉，见第 4 节）：

「拖动排序」与「修改碱基」进行中时，工具箱按钮会变红并改文案为「点此完成」，再次点击即退出该模式。

9运行机制与常见问题

运行机制

• 服务器端执行：与「拆峰」页不同，本页会把序列上传到服务器，由服务器调用 MAFFT / trimAl / IQ-TREE 可执行文件；页面顶部会出现全屏遮罩显示当前进度，完成后关闭。
• 三个阶段、三次请求：对齐、裁切、建树各对应一个接口（/api/mafft、/api/trim、/api/build），依次发出、串行等待。任一阶段失败会弹窗提示原因，且流水线不继续。
  「一键执行」就是替你把这三次请求按顺序发一遍；单独点三个按钮时，第 2、3 步会把页面上的序列重新上传（这样你手工改过的碱基 / 拖过的空位才会生效），而「一键执行」中途不给你编辑的机会，所以第 2、3 步改为只带第 1 步落盘时返回的时间戳定位表到服务器取文件，不再重复上传序列。
• 运行文件夹：一次建树会在服务器上新建一个以时间戳命名的文件夹 seq-files/<时间戳>/，里面放各片段的输入文件（its.fasta、lsu.fasta…）、partitions.nex，以及 IQ-TREE 的全部产物。IQ-TREE 的全部产物都落在这里（页面只回传两棵树与 NEXUS 文本，其余文件留在服务器上）。
• 定时清理：服务器会定期清理 seq-files/ 下超过保留期的中间文件与运行文件夹（默认 24 小时）。要长期保存的产物请及时用 zip 下载或自行归档。
• 建树耗时与超时：单片段 + 1000 次自举在普通机器上就是分钟级；多片段、序列多、模型复杂时会明显更久。服务器端建树的超时上限已放宽到 30 分钟（可配置）。等待期间页面会一直显示遮罩，不会假死。
• 页内出图：建树返回的 Newick 文本由前端还原真实叶名后，直接在本页绘制（与「树查看器」同一套算法），不跳转、不嵌 iframe。
• 单文件自包含：本页（以及「看树」页）的所有样式与脚本都写在页面里，没有任何外部 js/css 链接 —— 所以「另存为 / 下载本页」得到的 HTML 换台电脑、断网双击也能完整打开，看树部分仍然可交互，不会出现"页面在、树没了"或空白样式。
• 命名还原：为规避命令行对特殊字符的限制，后端处理时会把长标本名替换成短代号，返回前端时再逐一还原 —— 所以页面上看到的叶名始终是你的标本名。
• 特殊字符与引号：标本名里若含空格、逗号、分号、括号、方括号、撇号、井号、下划线，写进 Newick 时会按规范用单引号把整个名字包起来，名字内部的撇号写成两个（hawk's-eye → 'hawk''s-eye'）。这不是出错：不加引号时，这些字符会被解析器当成树的结构（逗号 = 分叉、括号 = 子树、空格 = 名字结束、方括号 = 注释、下划线 = 空格），名字会被截断甚至整棵树读不出来。页面上显示的叶名、下载的 .treefile、送往树查看器的内容三者始终一致，都是你的原名。

常见问题