Go os.CopyFS 遇到符号链接怎么判断：目录复制边界、错误返回与回滚清理

把配置目录复制到临时发布目录时，最容易误判的是符号链接：源目录里看见一个链接，目标目录却没有得到你以为的真实文件。os.CopyFS 复制的是 fs.FS 暴露出来的目录树；遇到不支持的文件类型、目标已存在或中途写入失败，应该把错误当成发布门禁，而不是继续使用半成品目录。

先把 os.CopyFS 的边界说清楚

os.CopyFS(dir, fsys) 的第一个参数是目标目录，第二个参数是源文件系统。常见源可以是 os.DirFS 返回的目录文件系统，也可以是嵌入资源。它的便利之处在于能递归复制目录，但“递归”不等于“安全覆盖”：目标中已有文件、源树中出现特殊类型，都会影响最终结果。

这里先看一个最小的复制入口。示例把源目录挂到 ./release-input，目标写入新建的 ./.release-staging：

package main

import (
    "fmt"
    "io/fs"
    "os"
)

func copyTree(src, dst string) error {
    if err := os.Mkdir(dst, 0o755); err != nil {
        return fmt.Errorf("create target: %w", err)
    }
    if err := os.CopyFS(dst, os.DirFS(src)); err != nil {
        return fmt.Errorf("copy %s to %s: %w", src, dst, err)
    }
    return nil
}

func main() {
    if err := copyTree("./release-input", "./.release-staging"); err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println("staging ready")
    _ = fs.ValidPath("config/app.yaml")
}

实际项目里不要把目标目录直接当成最终目录。先写入同级临时目录，完整校验通过后再切换目录名，后面会给出这个发布流程。

步骤一：复制前先识别符号链接

先用 fs.WalkDir 检查源树。DirEntry.Type() 可以快速看类型；为了让判断更明确，也可以调用 Info() 读取完整的 FileInfo。符号链接由 ModeSymlink 标记，不应被当成普通配置文件。

func rejectSymlink(root string) error {
    return fs.WalkDir(os.DirFS(root), ".", func(path string, entry fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        info, err := entry.Info()
        if err != nil {
            return fmt.Errorf("stat %s: %w", path, err)
        }
        if info.Mode()&os.ModeSymlink != 0 {
            return fmt.Errorf("symlink is not allowed: %s", path)
        }
        return nil
    })
}

这一步的成功状态很具体：遍历返回 nil，并且日志里没有 symlink is not allowed。如果业务确实需要链接，应把它单独列入白名单，同时记录链接目标和部署目录，不能静默跟随。

步骤二：把失败复制关进临时目录

复制操作可能已经写入一部分文件才返回错误。直接复用目标目录，下一次运行就会读到旧文件和半成品的混合状态。更稳的做法是创建同级临时目录，检查通过后再由发布流程切换。

func stageCopy(src, parent string) (string, error) {
    tmp, err := os.MkdirTemp(parent, ".copyfs-*")
    if err != nil {
        return "", fmt.Errorf("create staging dir: %w", err)
    }
    keep := false
    defer func() {
        if !keep {
            _ = os.RemoveAll(tmp)
        }
    }()

    if err := rejectSymlink(src); err != nil {
        return "", err
    }
    if err := os.CopyFS(tmp, os.DirFS(src)); err != nil {
        return "", fmt.Errorf("copy into staging: %w", err)
    }
    keep = true
    return tmp, nil
}

成功状态是函数返回一个仍然存在的临时目录路径；失败状态则是返回错误且临时目录已经被删除。清理错误不能覆盖原始复制错误，否则排查时只剩一个无关的删除失败。

步骤三：处理目标已存在与切换时机

os.CopyFS 不应该被当作覆盖发布器。目标目录里已有同名文件时，结果取决于具体文件和目录状态，调用前应明确目标是否为空，并让“切换”成为单独动作。

如果文件系统和部署方式允许原子切换，可以把临时目录命名成版本目录，再更新一个指向当前版本的入口；不具备这个条件时，也要先把旧目录改名为备份，切换失败再恢复。不要在复制尚未结束时让服务读取目标目录。

常见误区：链接存在不等于目标内容安全

有些代码只调用 os.Stat，然后根据返回结果决定是否复制。这个动作会跟随符号链接，读到的是链接目标的属性；如果你要检查链接本身，应使用 os.Lstat，或者在 WalkDir 中读取入口类型。两者语义不同，混用会让目录审计失去意义。

另一个误区是把 os.RemoveAll 当成常规覆盖手段。发布目录路径一旦拼接错误，删除动作的风险远高于复制动作。临时目录名应由 MkdirTemp 返回，并且清理只针对本轮生成的绝对路径。

相关问题

os.CopyFS 会自动跟随符号链接吗？

不要把它当成会安全跟随链接的工具。不同文件系统实现和特殊文件类型会带来边界，生产复制前应主动扫描并对符号链接作出明确策略。

复制失败后为什么不能继续使用目标目录？

因为失败可能发生在任意文件之后，目标目录已经是部分新文件、部分旧文件的混合物。临时目录失败即删，能让下一次运行从干净状态开始。

什么时候该用 os.Lstat 而不是 os.Stat？

要判断路径本身是不是符号链接时用 Lstat；要读取链接指向对象的属性时才使用会跟随链接的 Stat。

把复制流程收敛成四个检查点

1. 扫描源目录，拒绝未声明的符号链接和特殊文件。
2. 使用 MkdirTemp 创建同级临时目录，不直接写正式目录。
3. 复制、文件数和关键文件校验全部通过后，才进入目录切换。
4. 任一步失败都删除本轮临时目录，并把原始错误返回给上层。

这样处理后，os.CopyFS 只是复制动作，策略、门禁和回滚各自有清晰边界。目录里出现一个意外链接时，系统会在复制前给出可定位的错误，而不是把问题留到服务启动以后。