企业官网建设流程全解析

1. UltraEdit FTP 列不出目录，问题到底卡在哪

UltraEdit 内置 FTP 连接远程服务器后，登录提示成功，状态栏却一直停在“正在检索目录列表……”，左侧远程文件树空白，右键刷新也没反应。这个现象在 UltraEdit、Notepad++ 的 NppFTP 插件、甚至部分 IDE 的 SFTP 插件里都会出现，本质是同一类问题：控制连接通了，数据连接没通。

FTP 协议和普通 HTTP 不一样，它用两条连接干活。一条是控制连接，默认 21 端口，负责发命令、收状态码，你看到的“登录成功”就是这条连接给的反馈。另一条是数据连接，负责传目录列表和文件内容。列目录用的命令是 LIST 或 MLSD，服务器收到命令后，会另开一条数据通道把目录内容送回来。如果这条数据通道被防火墙挡了、被 NAT 设备丢了、或者客户端和服务器的被动模式协商对不上，控制连接还活着，但目录列表永远等不到，界面就卡在“正在检索目录列表”。

所以排查方向不是“账号密码对不对”，而是三件事：被动模式有没有开对、防火墙有没有放行数据端口、客户端配置有没有和服务器匹配。这篇按这三条线走，先讲 UltraEdit 里的账户和被动模式设置，再讲防火墙放行规则，最后给一套用 TaoToken 统一 Key 管理多工具 API 通道的 settings.json 骨架，方便你把 UltraEdit、编辑器插件、命令行工具的接入配置集中管起来，减少“每个工具配一遍、错一个地方查半天”的情况。

适合谁看：用 UltraEdit 连 FTP/SFTP 做远程编辑的开发者、运维，以及同时用好几个客户端工具、想统一管理接入配置的人。下面每一步都能直接照着做。

2. 先理解主动模式和被动模式的区别

在动手改配置前，花两分钟把模式搞清楚，后面排障会快很多。

主动模式（PORT）下，客户端告诉服务器“你来连我”，服务器主动发起数据连接回客户端。问题在于，客户端通常在 NAT 或防火墙后面，服务器根本连不进来，所以现代网络里主动模式基本不可用。

被动模式（PASV）下，客户端问服务器“你开哪个端口等我”，服务器返回一个临时端口，客户端主动去连这个端口。数据连接方向变成客户端到服务器，穿 NAT 和防火墙更容易。UltraEdit 的“被动模式（防火墙）”选项就是干这个的。

但被动模式也有坑：服务器返回的临时端口范围如果不固定，防火墙就得放行一整段端口；如果服务器在 NAT 后面，返回的可能是内网 IP，客户端连过去就超时。这就是为什么“登录成功但列不出目录”在被动模式下依然会发生。

注意：列目录失败和上传下载失败经常是同一个根因。先把目录列出来，再传文件，排障顺序不要反。

3. TaoToken 前置：统一 Key 管理多工具接入通道

UltraEdit 本身是编辑器，FTP 是它的内置功能，和 TaoToken 不直接耦合。但实际工作里，你往往同时开着 UltraEdit、命令行工具、AI 编码助手、脚本，每个都要配 API 地址和 Key。配置散落在各处，改一个 Key 要翻五六个地方，排查网络问题时也容易把“FTP 数据连接问题”和“API 通道配置问题”混在一起。

TaoToken 在这里的角色是统一接入层：一个 Key 管多个工具的 API 通道，配置集中写、集中改。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。先把 Key 拿到，后面 settings.json 骨架直接填进去。

拿 Key 的路径：进控制台创建 API Key，地址 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。创建后复制保存，Key 只显示一次。如果你要管的是编码类工具和 Agent 的长期通道，可以看 Coding Plan，地址 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。想先验证模型通不通，用模型对话页面，地址 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。Key 列表管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

这一步的目标不是“注册”，而是把后面要用的 Key 和地址准备好，让 UltraEdit 排障和 API 通道配置互不干扰。

4. 可复制配置：UltraEdit FTP 账户与被动模式设置

打开 UltraEdit，进入 FTP 账户管理器。路径是：高级（Advanced）→ FTP 账户管理器（FTP Account Manager），或者直接点工具栏的 FTP 图标。新建一个账户，填这几项：

关键在“服务器”标签页里的设置。找到“被动模式（防火墙）”复选框，勾上。这一步对应 excerpt 里提到的解决方案，也是列目录失败最常见的修复动作。勾选后 UltraEdit 会用 PASV 命令协商数据端口，而不是等服务器回连。

如果勾了被动模式还是列不出目录，继续在同一个设置页找“使用被动模式时使用服务器 IP”或类似选项。有些服务器在 NAT 后面，PASV 返回的是内网地址，勾上这个选项让客户端用控制连接的对端 IP 去连数据端口，能绕过一部分 NAT 问题。

再往下，如果服务器支持，把传输模式从 ASCII 改成二进制（Binary）。ASCII 模式在列目录时一般没问题，但传文件时可能改坏内容，顺手改掉省事。

配置完点“应用”，然后点“连接”。观察状态栏：如果从“正在检索目录列表”变成目录树出现，说明被动模式生效了。如果还是卡住，进入下一步防火墙排查。

5. 防火墙放行规则：数据端口才是关键

被动模式下，服务器会开一段临时端口做数据连接。防火墙如果只放行 21 端口，控制连接能通，数据连接被挡，症状就是登录成功但列不出目录。

先确认服务器端的被动端口范围。以常见的 vsftpd 为例，配置文件里这两项决定端口：

# /etc/vsftpd.conf pasv_enable=YES pasv_min_port=30000 pasv_max_port=30100

把范围固定下来，防火墙才好放行。范围别开太大，100 个端口够用。改完重启服务：

sudo systemctl restart vsftpd

然后在服务器防火墙放行这段端口。用 firewalld 的话：

sudo firewall-cmd --permanent --add-port=21/tcp sudo firewall-cmd --permanent --add-port=30000-30100/tcp sudo firewall-cmd --reload

用 ufw 的话：

sudo ufw allow 21/tcp sudo ufw allow 30000:30100/tcp sudo ufw reload

如果服务器在云平台上，安全组也要放行同样的端口范围，两层防火墙都要查。很多人只改了系统防火墙，忘了云安全组，结果还是列不出目录。

客户端这边，Windows 防火墙一般不用为被动模式单独开入站端口，因为数据连接是客户端主动发起的出站连接。但如果公司网络有出口防火墙，可能限制了大范围高端口出站，这时候要么换被动端口范围，要么找网络管理员放行。

注意：不要为了图省事直接把防火墙全关。关防火墙能“解决”问题，但把服务器暴露在公网风险太大。正确做法是精确放行必要端口。

6. 用 settings.json 统一管理多工具 API 通道

FTP 排障和 API 通道是两条线，但配置管理可以统一。下面给一个 settings.json 骨架，把 TaoToken 的接入信息集中写，UltraEdit 之外的命令行工具、脚本、编码助手都从这里读，改 Key 只改一处。

{ "api": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "timeout_ms": 30000, "retry": { "max_attempts": 3, "backoff_ms": 800 } }, "tools": { "ultraedit_ftp": { "passive_mode": true, "use_server_ip_in_pasv": true, "transfer_mode": "binary", "control_port": 21, "pasv_port_range": "30000-30100" }, "cli_agent": { "enabled": true, "model": "claude-sonnet", "channel": "coding-plan" } }, "logging": { "level": "info", "log_ftp_commands": true } }

几个字段说明。base_url 固定用 https://taotoken.net/api ，不要加 UTM 参数到 API 地址里。api_key 填你创建的那把。tools.ultraedit_ftp 里的 passive_mode 和 use_server_ip_in_pasv 对应前面 UltraEdit 界面里的两个勾选项，写在这里是为了让配置可版本化、可复制到其他机器。pasv_port_range 和服务器端配置保持一致，排查时一眼能对上。logging.log_ftp_commands 打开后，UltraEdit 的 FTP 命令日志会记录 PASV 协商过程，列目录失败时能看到服务器返回的端口和 IP，定位很快。

如果你用的是 Claude Code 这类编码工具，接入配置可以参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude-code-anthropic&utm_campaign=rewrite ，把 base_url 和 Key 指向同一套，避免多份配置漂移。

7. 验证请求与成功结果

配置改完，按这个顺序验证，每一步都有明确的成功标志。

第一步，验证控制连接。在 UltraEdit 里点连接，状态栏出现“已登录”或“登录成功”，说明 21 端口和账号密码没问题。

第二步，验证被动模式协商。打开 UltraEdit 的 FTP 日志窗口（视图 → FTP 日志），连接后找 PASV 命令的返回。成功的话会看到类似：

命令: PASV 响应: 227 Entering Passive Mode (192,168,1,10,117,48)

括号里前四个数字是 IP，后两个数字算端口：117×256+48=30000。这个端口要落在你放行的范围内。

第三步，验证数据连接。PASV 返回后，客户端会去连那个端口，日志里出现 LIST 或 MLSD 命令，然后目录树出现。成功标志就是左侧远程目录能展开，能看到文件和子目录。

第四步，验证 API 通道。用命令行发一个请求，确认 Key 和 base_url 通：

curl -s -o /dev/null -w "%{http_code}\n" \ -H "Authorization: Bearer sk-你的Key" \ https://taotoken.net/api/models

返回 200 说明通道正常。返回 401 检查 Key，返回超时检查网络出口。

如果第三步失败但前两步成功，回到防火墙那节，重点查 PASV 返回的端口有没有被挡。如果 PASV 返回的 IP 是内网地址，勾上“使用服务器 IP”选项再试。

8. 本篇常见错排查

错误一：勾了被动模式还是列不出目录。先看 PASV 返回的端口范围，和防火墙放行的是不是一致。服务器改了 pasv_min_port 但防火墙没同步，是最常见的原因。再看 PASV 返回的 IP，如果是 10.x 或 192.168.x 而客户端在公网，需要开 use_server_ip_in_pasv 或在服务器配置 pasv_address 指定公网 IP。

错误二：登录就失败，不是列目录问题。这属于控制连接问题，检查端口、账号、密码、服务器类型（FTP 还是 SFTP）。SFTP 走 22 端口，和 FTP 的 21 完全不同，选错类型会直接连不上。

错误三：能列目录但传文件失败。数据连接已经通了，问题可能在传输模式或磁盘权限。把传输模式改成二进制，检查远程目录的写权限。

错误四：时好时坏。被动端口范围太小，并发连接把端口占满。把范围扩大到 100 个以上，或者减少同时连接数。

错误五：公司网络里只有 UltraEdit 不行，浏览器能访问 FTP。浏览器可能走了不同的出口策略，或者用了 HTTP 代理。检查 UltraEdit 有没有配代理，以及公司出口防火墙对高端口的限制。

错误六：API 请求 401。Key 复制时带了空格，或者用了已删除的 Key。去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 重新确认。

9. 把配置固定下来，下次直接复用

UltraEdit FTP 列不出目录，九成情况是被动模式没开对，或者被动端口被防火墙挡了。把服务器被动端口范围固定、防火墙精确放行、客户端勾上被动模式和服务器 IP 选项，这三步做完基本能解决。settings.json 骨架的作用是把 FTP 参数和 API 通道配置放在一起，换机器、换工具时直接复制，不用重新回忆每个选项在哪。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到通道配置问题先查这里。模型验证用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，长期编码和 Agent 通道用 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。把 Key 和地址统一管起来，FTP 排障和 API 接入就不会互相干扰了。