STACIO WIKI · 用户指南
Stacio 文件指南
1. 文件能力概览
Stacio 的 Files 工作区把本地目录、远端目录和传输队列放在同一个窗口中。根据会话协议，Files 使用内置 SSH/SCP、SFTP 或 FTP 运行时，不依赖系统 scp、sftp 或 rsync 命令。
| 会话来源 | 主要能力 | 当前限制 |
|---|---|---|
| 已连接 SSH 终端 | 浏览、搜索、新建、重命名、删除、chmod、上传、下载、Remote Edit、比较、备份和恢复 | Files 绑定当前 SSH 运行时；终端断开后需要重连或重新绑定。 |
| SCP 会话 | 与 SSH Files 基本一致，传输使用内置 SCP | 需要有效 SSH 认证和已确认的主机密钥。 |
| SFTP 会话 | 浏览、搜索、目录操作、chmod、上传、下载和编辑 | 服务端必须启用 SFTP 子系统。 |
| FTP 会话 | 浏览、新建、重命名、删除、上传、下载和编辑 | FTP 不加密；当前不提供远端搜索、chmod 和双文件比较。 |
“文件同步”高级授权主要控制同步已变更编辑文件等批量 Remote Edit 同步入口。普通浏览和传输是否可用，还取决于当前协议、连接状态和远端权限。
Files 不单独解析一个新的远端地址，而是继承 SSH 终端或 SFTP/FTP/SCP 会话的连接端点。直接创建文件协议会话时，大多数场景使用 IP，也可以使用域名：
| 会话 | 主机字段 | 端口字段 | 显示端点 |
|---|---|---|---|
| SFTP/SCP | 192.168.1.20 |
22 |
192.168.1.20:22 |
| SFTP/SCP 自定义端口 | 192.168.1.20 |
2222 |
192.168.1.20:2222 |
| FTP | 10.0.0.15 |
21 |
10.0.0.15:21 |
| 域名会话 | files.example.com |
对应协议端口 | files.example.com:端口 |
在保存会话表单中不要把 192.168.1.20:2222 整体填入主机字段。远端路径框只填写 ~、/srv/app 等文件路径，也不能填写 IP、域名或 URL。
2. 打开 Files
2.1 从 SSH 终端打开
- 打开并选中一个已经连接成功的 SSH 标签页。
- 选择
视图 > 文件，或点击工具栏文件。 - Files 默认绑定当前终端，并从远端主目录
~开始加载。 - 如果启用了目录跟随，终端中成功执行
cd后，Files 会尝试切换到同一目录。
若提示“当前没有可用的 SSH 文件上下文”，请先确认选中的是正在运行的 SSH 终端，而不是本地 Shell、Telnet、VNC、浏览器、分屏容器或已断开的标签。
2.2 直接打开文件协议会话
从左侧会话列表打开 SFTP、FTP 或 SCP 会话时，会直接进入文件工作区。连接过程仍会执行对应认证；SSH 系协议还会执行主机密钥校验。
2.3 Files 与终端的绑定
- Files 只对当前绑定的远端运行时执行操作；
- 切换终端时，检查会话上下文中的 IP/域名、端口、账号以及顶部路径是否都属于预期目标；
- 关闭或重连终端后，正在进行的任务可能停止，Files 会显示断开状态；
- 未保存的 Remote Edit 内容关闭前会请求确认，不应依赖断线自动保存。
3. 认识文件工作区
3.1 本地与远端两栏
独立文件工作区通常包含：
- 左侧
本地文件：当前 Mac 上的目录； - 右侧
文件：当前会话的远端目录； - 右侧可展开的编辑器或媒体预览；
- 检查器中的
传输队列。
可以拖动分隔线调整宽度。界面会保存部分工作区宽度，但不会改变文件本身。
3.2 远端工具栏
常用控件包括：
- 返回上一级目录；
- 路径输入框；
- 刷新远端目录；
- 搜索；
- 显示或隐藏 dotfile；
- 上传文件或文件夹；
- 下载所选项目；
- 更多操作菜单。
列表可显示名称、类型、大小、修改时间、属主和权限等信息。具体字段取决于协议和服务端返回的数据。
4. 浏览与定位
4.1 路径规则
~表示远端账号主目录；/表示远端文件系统根目录；- 可以在路径框输入绝对路径或
~/...路径； - 双击目录进入，使用“返回上一级目录”回到父目录；
- 路径无权限、已被删除或包含不安全内容时，Stacio 会取消操作并显示错误。
不要根据界面路径推断自己拥有写权限。读取、创建、改名、删除和 chmod 可能分别受到不同的远端权限限制。
4.2 隐藏文件
工具栏的隐藏文件按钮可临时显示或隐藏以 . 开头的项目。新 Files 面板的默认状态由Stacio > 设置 > 文件 > 默认显示隐藏文件控制。
显示 .env、.ssh、.config 等文件时要注意截图、AI 上下文和屏幕共享中的敏感内容。
4.3 远端搜索
- 点击搜索按钮。
- 输入文件名关键字。
- 设置搜索深度，范围为
1到20，默认值为5。 - 从结果中打开文件或定位到所在目录。
- 关闭搜索栏返回普通目录列表。
搜索从当前目录开始。深度越大，访问的目录越多，可能增加服务器负载和等待时间。生产主机上应先用较小深度，并避免从 / 进行宽泛搜索。FTP 会话当前不提供此搜索入口。
4.4 与终端联动
远端项目右键菜单可提供：
复制文件路径；将文件路径复制到终端；将文件名复制到终端；- 鼠标中键把文件名发送到当前绑定终端。
发送到终端只负责写入文本，不代表路径已安全转义，也不代表命令已执行。包含空格、引号或 Shell 元字符时，应在提交命令前检查引用。
5. 上传与下载
5.1 上传文件
- 在远端栏进入目标目录。
- 点击上传菜单，选择
上传文件或上传文件夹。 - 选择本地项目。
- 若目标已存在，按冲突策略处理。
- 在
传输面板确认任务状态和最终字节数。
也可以把 Finder 或本地文件栏中的文件拖到远端目录。拖到某个远端目录行时，该目录会成为目标；拖到列表空白处时，使用当前目录。
5.2 下载文件
- 在远端列表选择一个或多个文件或目录。
- 点击下载按钮，或右键选择
下载。 - 单个文件选择保存位置；多个项目选择目标文件夹。
- 在本地文件栏或 Finder 中验证下载结果。
远端项目也可直接拖到左侧本地目录。下载完成通知不等于内容正确；重要文件仍应核对大小、哈希或可解析性。
5.3 传输冲突
目标路径已存在时可选择：
| 策略 | 行为 | 适合场景 |
|---|---|---|
| 每次询问 | 每个冲突显示选择 | 默认且最保守。 |
| 保留两份 | 为新项目生成不冲突名称 | 不确定是否可以覆盖时。 |
| 覆盖 | 用传输内容替换目标 | 已验证目标和版本时。 |
| 重命名 | 为新副本选择或生成名称 | 需要显式区分版本时。 |
| 跳过 | 不传输冲突项目 | 批量任务只补缺失文件时。 |
默认策略在Stacio > 设置 > 文件 > 传输冲突策略中配置。固定为“覆盖”会减少提示，也会扩大误操作影响；生产环境建议保留“每次询问”。
6. 传输队列
视图 > 传输显示上传和下载任务，包括方向、文件、进度、状态和诊断信息。不同状态下可用操作不同：
暂停：中断当前任务并保留可恢复信息；恢复：从暂停状态重新加入队列；停止：停止当前任务并保留重新开始入口；重试：再次运行失败任务；重新开始：从头执行暂停或可重试任务；清理已结束：从队列视图移除已完成、失败或取消项。
网络或服务器不支持续传时，“恢复”可能仍需重新发送部分或全部内容。关闭会话或应用会停止依赖该运行时的任务；不要把队列中的queued或running当作远端已收到完整文件。
完成判断至少包含：
- 任务状态为已完成；
- 已传字节与预期字节一致；
- 目标文件存在且大小合理；
- 对配置、归档或数据库文件执行专项校验。
7. 远端文件操作
7.1 新建、重命名与删除
在更多菜单或右键菜单中可执行：
新建远端目录；新建远端文件；重命名远端项目；删除远端项目。
重命名输入的是新的远端路径。删除会显示确认，但远端删除通常不进入 macOS 废纸篓，也不保证可恢复。删除目录前应确认其中内容和当前主机。
7.2 属性与权限
右键选择属性或权限查看远端元数据。SSH/SCP/SFTP 会话可使用修改远端权限输入八进制 chmod 值，例如：
644
755
600输入前应理解文件和目录的读、写、执行语义。不要为解决权限问题直接使用 777；应先确认属主、属组、运行账号和最小所需权限。FTP 当前不提供 chmod。
8. Remote Edit
8.1 在 Stacio 中编辑
- 选择可编辑的文本文件。
- 右键选择
在 Stacio 编辑器中打开，或在更多菜单选择编辑本地副本。 - Stacio 把远端内容下载到自建缓存并在内置编辑器打开。
- 修改后保存，观察“正在保存”“已保存”或“保存失败”状态。
- 在远端重新读取或用应用专项检查确认内容生效。
编辑器支持多个文档标签。未保存文档会显示状态标记；关闭编辑器或工作区时会询问保存、放弃或取消关闭。
8.2 使用外部应用
右键可选择：
打开方式...；使用默认程序打开...；- 使用默认文本编辑器打开本地副本。
外部应用只编辑本地缓存。若启用设置 > 文件 > 检测本地编辑副本变化，Files 会检测变化并提示通过传输队列同步；它不会在没有提示的情况下直接覆盖远端文件。
8.3 保存与远端冲突
保存时，Stacio 会尽量检查远端修改时间。若文件在打开后已被其他人或进程修改，会阻止直接覆盖并报告远端已变化。
遇到冲突时：
- 保留当前本地副本；
- 重新下载远端最新版本；
- 比较差异；
- 手工合并；
- 另存备份后再上传。
不要通过反复点击保存绕过远端变化提示。
8.4 同步已变更编辑文件
更多菜单中的同步已变更编辑文件会扫描当前会话的 Remote Edit 缓存，把检测到的本地变化加入上传队列。该入口受“文件同步”License 控制。
批量同步前应逐项核对文件、主机和环境。入口完成只表示任务已入队，仍需在传输队列检查每个上传结果。
9. 预览、打开与比较
- 可预览媒体文件可选择
在 Stacio 中预览； - 其他文件可下载本地副本并用默认应用或指定应用打开；
- 选择两个远端文件后可使用
比较文件...； - 比较功能会先下载两个本地副本，再调用 FileMerge；未安装 Xcode 或找不到 FileMerge 时会提示不可用；
- FTP 会话当前不提供双文件比较。
打开或预览大文件会产生本地缓存和传输等待。包含客户数据或密钥材料的文件不应交给无权访问的本地应用。
10. 备份与恢复
10.1 备份编辑文件
当内置编辑器打开时，检查器顶部会显示备份当前编辑文件按钮：
点击备份按钮。
选择当前已打开的一个或多个文件。
选择备份到远端同目录或下载到本地。
Stacio 使用以下名称生成副本：
原文件名-yyyyMMddHHmm.bak验证备份文件存在、大小合理且可以读取。
远端备份通过复制当前远端文件生成；本地备份通过传输队列下载。仅看到备份任务并不证明备份可恢复。
10.2 恢复备份
点击检查器顶部恢复备份文件，可选择：
- 从当前远端目录选择符合命名规则的
.bak文件； - 从本地选择符合命名规则的备份文件。
恢复会去掉时间戳和 .bak 后缀，并写回原文件名。若目标已存在，应按冲突策略和变更流程处理。恢复后必须重新读取文件，并运行语法检查、服务健康检查或业务验证。
11. 文件设置与缓存
Stacio > 设置 > 文件可配置：
| 设置 | 影响 |
|---|---|
| 默认开启目录跟随 | 新 Files 面板是否跟随终端 cd。 |
| 默认显示隐藏文件 | 新面板是否显示 dotfile。 |
| 检测本地编辑副本变化 | 是否发现外部编辑器产生的本地修改。 |
| 传输冲突策略 | 新传输遇到同名目标时的默认行为。 |
| 默认显示传输队列 | 新工作区是否直接显示队列。 |
| 清除缓存 | 清除 Stacio 自建的 Remote Edit 和临时远端文件缓存。 |
清除缓存前检查“未保存远程编辑”数量。缓存清理不会删除真实下载目录、会话数据库或凭据，但会让尚未同步的本地编辑副本无法继续恢复。
12. 安全与变更建议
- 首先确认 IP/域名、端口、账号、协议、远端路径和环境；
- 对 FTP 只在受信任网络中使用，并优先迁移到 SFTP；
- 不在文件名、宏、日志或截图中暴露密码、Token 和私钥；
- 修改生产配置前创建已验证备份，并准备回滚命令；
- 删除、覆盖、chmod、恢复和批量同步都按变更操作处理；
- 传输完成后用哈希、解析器、配置测试或应用健康检查验证；
- 结束工作后清理不再需要的敏感本地副本和诊断材料。
13. 常见问题
| 现象 | 检查与处理 |
|---|---|
| 目录无法加载 | 检查连接状态、路径、远端权限、SFTP 子系统或 FTP 服务。 |
| 连接到了错误文件服务器 | 核对会话的独立主机和端口字段、账号与环境，不要只看会话名称。 |
| 列表返回数据无法解析 | 确认目标系统兼容、路径安全；刷新后仍失败则查看应用日志。 |
| 搜索按钮不可用 | FTP 不支持远端搜索；其他协议检查连接上下文。 |
| 上传或下载认证失败 | 重新检查会话凭据、私钥口令和 SSH agent。 |
| 主机密钥已变更 | 停止操作并通过独立渠道核验，不要直接覆盖信任记录。 |
| 本地或远端磁盘已满 | 检查目标卷空间和 inode，清理前取得授权。 |
| 保存提示远端已变化 | 保留本地副本，重新下载、比较并手工合并。 |
| 比较功能不可用 | 选择恰好两个文件，并确认本机安装了 Xcode/FileMerge；FTP 不支持。 |
| chmod 无反应 | FTP 不支持；SSH/SFTP 检查属主和权限。 |
| 同步按钮灰色 | 在帮助 > License检查文件同步授权。 |
| 清理缓存前提示未保存编辑 | 先同步、导出或备份这些本地副本，再执行清理。 |
提交问题时提供 Stacio 版本、协议、操作方向、源和目标路径的脱敏摘要、任务时间、队列状态及错误信息；不要附带凭据或敏感文件正文。