有阵子微信群几乎每天都有人问同一个问题Dify本地部署好之后工作流里的代码执行节点一直报错打开日志一看不是config.yaml缺失就是Operation not permitted。作为一个把Dify从0.6时代一路用到1.17.x的人我在沙盒容器部署上踩过的坑一点都不比跑业务逻辑少。这篇就专门聊聊Dify沙盒容器部署时最常见的两个拦路虎config.yaml文件缺失以及系统调用权限被限制。如果你正准备本地部署Dify或者已经部署完成但代码节点跑不通这篇文章应该能帮你少走不少弯路。1. 先把Dify沙盒容器的部署逻辑盘清楚很多人一上来就直接照抄启动命令结果出了错也不知道去哪里排查。我建议还是先花五分钟搞清楚Dify沙盒容器在这个项目里到底扮演什么角色后面遇到问题才有方向。1.1 沙盒容器到底在Dify里干什么Dify是一个可视化的大模型应用开发平台最吸引人的能力之一就是工作流编排。你可以在工作流里拖一个“代码执行”节点写几段Python或者Node.js代码让它在LLM处理前后做数据清洗、格式转换、逻辑判断。这个能力看起来很轻量但背后其实藏着一个安全设计用户写的代码不能直接跑在Dify主服务的进程里否则一段os.system(rm -rf)级别的代码就能把整个平台干掉。所以Dify默认使用独立沙盒容器来执行这些不可信代码。在docker-compose的服务列表里你会看到一个名字叫sandbox的服务镜像一般是langgenius/dify-sandbox。Dify主服务收到代码执行请求后会把代码和参数打包发给沙盒沙盒在受控环境里跑完再把结果传回来。除了工作流代码节点文档处理、模板转换、数据提取这些需要动态计算的任务也可能依赖沙盒容器。理解了这个关系你就明白为什么沙盒容器一挂整个工作流都会受影响。它不是边缘组件而是Dify本地部署里不可缺少的一环。1.2 config.yaml为什么是第一个坑沙盒容器不是拿到代码就能跑的它启动时需要读一个config.yaml配置文件。这个文件里定义了沙盒的监听端口、API密钥、worker数量、单次请求体积上限、文件存储路径、Python依赖白名单等一堆关键参数。简单说沙盒容器靠这个文件知道自己是谁、能做什么、不能做什么。如果这个文件缺失沙盒容器可能直接退出也可能反复重启Dify主服务调用沙盒接口时就会拿到连接失败或者服务不可达的错误。你在页面上看到代码执行节点报错打开Dify服务日志才发现真正原因是open /app/config.yaml: no such file or directory。很多新手这时候还在排查工作流配置其实问题根本不在工作流而在沙盒的启动配置。我记得有一次升级版本老沙盒容器还在跑新配置文件没有跟上docker compose up -d以后日志一直报找不到config.yaml。当时我第一反应也是Dify本体出了问题后来单独看沙盒日志才定位到是挂载的配置文件路径不对。所以遇到代码节点异常先查沙盒日志这个习惯比任何技巧都有用。1.3 系统调用权限为什么这么敏感沙盒除了要保证Dify平台本身不死还要防止用户代码通过操作系统的系统调用syscall越权。Linux系统里用户程序要读写文件、启动进程、访问网络都需要经过系统调用。普通容器虽然已经隔离了文件系统和进程空间但某些系统调用仍然可能影响宿主机比如ptrace、mount、reboot这一类危险操作。Docker容器默认有seccomp和capabilities双重机制来限制系统调用权限。seccomp可以理解成一道“系统调用安检门”每个调用进来都要检查是否在白名单里capabilities则是一张张“特权许可证”比如要挂载文件系统就需要CAP_SYS_ADMIN要跟踪进程就需要CAP_SYS_PTRACE。Dify沙盒为了安全通常还会在代码层再做一层校验限制可用的系统调用白名单。难点就在这里dify沙盒遇到权限问题时报错往往只有一个笼统的Operation not permitted你很难一眼看出是Docker的seccomp拦的还是capabilities不够还是沙盒自己配置的限制。这个问题我在第3章会专门拆解这里先记住一个结论权限报错不等于危险它可能是设计如此也可能是配置不到位。搞清楚是哪一层拦的才能对症下药。2. 从零开始部署先把基础跑通再谈权限接下来是实操部分。我会尽量按我实际部署的顺序来讲每一步都会说清楚为什么这么做而不是只丢给你一条命令。2.1 准备环境Dify官方推荐的部署方式是Docker Compose所以本地必须有Docker环境。Windows和macOS建议安装Docker DesktopLinux建议直接用Docker Engine Docker Compose插件。无论哪种方式都先确认版本docker --version docker compose versionDify对资源不算太苛刻但沙盒容器要跑Python解释器再加上数据库、Redis、API服务这些建议至少给Docker分配4核CPU、8GB内存、20GB可用磁盘。如果你还要本地跑embedding模型或者大模型内存尽量加到16GB以上。Windows用户尤其注意Docker Desktop的内存设置默认可能只有2GB一定要去Settings里调高否则部署到一半OOM报错会非常难查。另外Docker Desktop需要开启文件共享因为Dify的docker-compose会把本机目录挂载进容器。如果你用的是Windows建议把Dify项目放在一个明确的目录比如C:\work\dify然后在Docker Desktop的File Sharing里确认这个盘符或者目录被允许。2.2 获取Dify源码并初始化.env部署Dify第一步不是docker compose up而是先把工程目录准备好。推荐用官方Git仓库拉取git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env如果你从Release页面下载压缩包解压后进入dify-main/docker目录操作也差不多。重点是cp .env.example .env这一步很多人会漏掉。Dify会把大量运行参数集中在.env文件里包括各组件端口、数据库账号密码、密钥等。漏了这一步后面直接docker compose up -d很多服务会因为读不到环境变量而启动失败。复制完.env以后打开它搜索sandbox相关的配置项。不同版本字段名可能不一样常见的是SANDBOX_API_KEY或者DIFY_SANDBOX_API_KEY。这个key是一串随机字符串作用是让Dify主服务和沙盒容器之间互相识别。你先把这一项记下来后面配置沙盒的config.yaml时会用到。2.3 解决config.yaml缺失从镜像里“抄”一份出来Dify沙盒容器启动时会读取容器内/app/config.yaml。很多部署教程默认你有这个文件但实际下载的包可能因为版本差异、目录裁剪、Git submodule未拉全等原因本地根本没有sandbox/config.yaml。这时候不要慌最稳妥的办法是从沙盒镜像里直接导出一份默认配置。假设你的沙盒镜像tag是0.2.10先确认本地已经拉取了镜像docker pull langgenius/dify-sandbox:0.2.10然后用以下命令直接让容器输出默认的配置文件重定向到宿主机mkdir -p ./sandbox docker run --rm --entrypoint cat langgenius/dify-sandbox:0.2.10 /app/config.yaml ./sandbox/config.yaml如果入口不是cat也可以用shell方式导出docker run --rm --entrypoint sh langgenius/dify-sandbox:0.2.10 -c cat /app/config.yaml ./sandbox/config.yaml导出来以后打开这个文件你会看到类似这样的结构app: port: 8194 debug: false key: your-sandbox-key max_workers: 4 max_request_size_mb: 20 max_execution_time_seconds: 5 files: enable: true max_files: 10 max_file_size_mb: 10 storage: type: local local: path: /sandbox/data python: allow_system: false libs: - requests - numpy - pandas不同版本的字段会有差异但核心逻辑差不多。你要重点修改两处第一把app.key改成.env里配置的沙盒API密钥保证两个服务能对得上第二确认storage.local.path指向一个容器内有权限写的目录这个后面权限问题还会提到。如果你拿到的镜像默认没有config.yaml.example文件那上面这个方法就是最可靠的方案。2.4 挂载config.yaml到沙盒容器导出配置文件以后还要确保docker-compose真正把这个文件挂载进容器。打开docker/docker-compose.yaml找到sandbox服务。常见配置类似sandbox: image: langgenius/dify-sandbox:0.2.10 container_name: docker-sandbox restart: always environment: API_KEY: ${SANDBOX_API_KEY} volumes: - ./sandbox/config.yaml:/app/config.yaml ports: - 8194:8194注意挂载路径宿主机目录是./sandbox/config.yaml也就是docker目录下的sandbox子目录。如果你的config文件放到了其他位置比如解压目录根路径那这里的宿主机路径也要同步改。挂载方向是宿主机文件:容器内文件别写反了。改完以后先验证一下Compose配置有没有语法问题docker compose config -q这个命令不会输出一堆信息有错会直接提示。确认没问题后先只启动沙盒容器方便观察docker compose up -d sandbox docker compose logs -f sandbox如果日志里干干净净没有config.yaml相关报错说明沙盒容器已经正常起来了。这时候用命令看下监听端口curl http://localhost:8194/health不同版本健康检查路径可能有差异如果返回失败但不报连接拒绝说明服务起来了一部分继续查日志即可。2.5 启动完整Dify并验证代码执行节点沙盒没问题以后再把整套服务启动起来docker compose up -d等到所有容器都变成running状态打开浏览器访问Dify管理后台创建或进入一个应用在工作流里拖一个“代码执行”节点写入最简单的测试代码def main() - dict: return {result: hello sandbox}运行这个节点如果能正常返回hello sandbox说明Dify主服务和沙盒容器之间的通信链路打通了。如果这时候报错比如HTTP 403或者Sandbox service unavailable优先检查.env里的SANDBOX_API_KEY和config.yaml里的app.key是否一致。这个一致性问题是我见过最多的问题之一两个文件各写各的结果Dify主服务把请求发过去沙盒直接拒绝。到这里基础部署就已经跑通了。大部分人的问题其实也解决了一半。接下来才是本文的重头戏系统调用权限问题。3. 深度拆解系统调用权限报错我见过很多同学在部署成功以后写第一段正经业务代码时被Operation not permitted卡住。这个报错看着简单背后却可能藏着至少三个不同层面的限制。我习惯把这层限制拆成“Docker层”和“沙盒代码层”来看。3.1 典型的权限报错长什么样先列举几个我在实践中遇到过的报错你可以对照自己的情况。第一种是文件操作报错。比如代码节点里创建一个临时文件再删除def main() - dict: import os path /tmp/test.txt with open(path, w) as f: f.write(test) os.remove(path) return {result: os.path.exists(path)}运行结果可能不是预期的False而是RuntimeError: [Errno 1] Operation not permitted。第二种是启动子进程报错。比如想在代码节点里调用系统命令def main() - dict: import subprocess result subprocess.run([ls, /], capture_outputTrue, textTrue) return {stdout: result.stdout}同样可能遇到PermissionError: [Errno 13] Permission denied或者OSError: [Errno 1] Operation not permitted。第三种是访问挂载目录报错。比如沙盒配置了storage.local.path: /sandbox/data工作流里要写入文件结果一直提示没有权限。这些报错从Dify页面上看都是红色异常但根因并不一样。第一种可能是seccomp拦截了unlink系统调用第二种可能是容器capabilities不足第三种可能是宿主机目录的属主和容器内用户不一致。不逐层排查很容易瞎试一通浪费一下午。3.2 三层排查法先看Docker配置再进容器验证遇到权限报错我第一件事是看沙盒容器的Docker配置。docker inspect docker-sandbox --format {{json .HostConfig.SecurityOpt}} docker inspect docker-sandbox --format {{json .HostConfig.CapAdd}} docker inspect docker-sandbox --format {{json .HostConfig.CapDrop}} docker inspect docker-sandbox --format {{json .Mounts}}第一条命令会返回seccomp相关的配置。如果里面有seccompunconfined说明Docker层没启用seccomp限制如果显示的是某个profile文件路径说明有seccomp策略。第二条和第三条命令分别展示额外添加和剥离的capabilities。有些镜像会默认CapDrop: [ALL]再单独加极少量的capability这种情况下稍微敏感一点的操作都会被挡。最后一条命令则能帮你确认挂载目录权限来源。查完配置以后再进容器内部手动执行同样的代码docker exec -it docker-sandbox /bin/sh在容器里跑一下os.remove(/tmp/test.txt)或者subprocess.run([ls])。如果容器内一切正常但通过Dify代码节点执行报错那问题十有八九出在沙盒自身的代码层白名单上。如果容器内就报同样的错那首先要怀疑Docker启动参数和底层权限。这个对比实验非常重要。它能把问题范围缩小避免你在Dify配置里翻来覆去找一个其实根本不存在的错误。3.3 临时放行与精准放行确认是Docker层拦截以后可以做一个快速验证临时给sandbox服务加上特权模式看看问题是否消失。sandbox: image: langgenius/dify-sandbox:0.2.10 privileged: true重启沙盒容器再跑一次报错的代码。如果权限问题消失说明确是容器权限不够。但千万别把这个配置留在生产环境里privileged等于把所有敏感权限都放开了非常危险。它只是用来确认方向的。如果你只想确认是否seccomp拦截也可以临时放行seccompsandbox: image: langgenius/dify-sandbox:0.2.10 security_opt: - seccompunconfined同样只用于测试。seccompunconfined意味着系统调用安检门直接不查了等于把Docker层的一道保险拆掉。测试完就要改回来然后观察日志找到具体被拦截的系统调用名称。如果是沙盒代码层的白名单限制就需要改config.yaml。部分版本的Dify沙盒配置里会有类似allowed_syscalls的字段用来声明允许的系统调用。你可以在源码里搜一下allowed_syscalls这个关键词看看你的版本是否支持。如果支持把你报错中缺失的系统调用明确加进去比如unlink、mkdir、getcwd等。如果不支持那通常意味着沙盒作者刻意锁死了某些调用业务代码里就应该尽量避免使用。我在实际项目里的策略是能用纯Python文件操作解决的问题绝不在沙盒里去调用系统命令。沙盒越安全平台越稳定。如果业务确实需要读取文件、写文件、调用外部接口那就通过Dify平台的工具节点或者自定义API服务来做而不是把所有事情都塞进代码节点。这既是安全实践也是架构上更清晰的做法。3.4 一个很隐蔽的“假权限问题”挂载目录属主不对还有一类权限报错表面看是Operation not permitted实际上跟seccomp一点关系都没有就是单纯的文件系统权限不对。Dify沙盒容器内部通常以非root用户运行宿主机目录挂载进容器以后目录的owner和容器内用户不一定匹配。比如sandbox/data目录在宿主机上属于root容器内用户是UID 1000那么容器内写文件就会报权限不足。排查方法是进入容器尝试在配置的数据目录下创建文件docker exec -it docker-sandbox /bin/sh touch /sandbox/data/test.txt如果显示Permission denied那基本就是这个原因。解决方式很简单回到宿主机把目录属主改成容器内用户对应的UIDchown -R 1000:1000 ./sandbox/data chmod -R 755 ./sandbox/data或者临时把config.yaml里的storage.local.path改成/tmp先验证文件读写是否恢复。/tmp通常对所有用户可写能帮你快速区分是“代码被系统限制”还是“目录本身不可写”。这个问题在Windows的Docker Desktop里又有另一层麻烦因为文件共享权限受Docker Desktop设置影响如果原本就报错建议先检查File Sharing配置。4. config.yaml与权限问题速查表、部署后的小经验最后一章我整理一个速查表把常见问题和排查路径放到一起方便你遇到问题时直接对照。后面再补两条我自己的部署习惯绝对是实战里摔出来的经验。4.1 常见问题速查表症状可能原因解决办法sandbox容器一直重启容器内没有config.yaml挂载路径不对从镜像导出config.yaml检查docker-compose中volumes路径日志提示open /app/config.yaml: no such file or directory本地缺少沙盒配置文件用docker run --entrypoint cat导出默认配置再编辑Dify工作流代码节点报“Sandbox service unavailable”Dify主服务和沙盒的API key不一致对比.env中SANDBOX_API_KEY和config.yaml中app.key统一后重启代码节点删除临时文件报Operation not permittedseccomp拦截或沙盒系统调用白名单用docker inspect查看SecurityOpt临时seccompunconfined测试再精准放行代码节点调用subprocess报Permission denied容器capabilities被剥离查看HostConfig.CapDrop按需cap_add业务上尽量不依赖subprocess写入/sandbox/data目录报权限错误宿主机目录属主与容器用户不匹配chown -R 1000:1000 ./sandbox/data或临时改用/tmp验证docker compose拉镜像失败网络问题或镜像源不稳定多试几次docker compose pull或配置系统级registry mirror这张表不用背出现问题时把对应行找出来按照“先看日志再看Docker配置最后看沙盒配置”的顺序走基本都能解决。4.2 升级Dify版本时要特别小心的点Dify社区更新节奏很快从1.15到1.17.1功能变化大配置结构也在微调。升级时最容易翻车的就是沙盒组件镜像tag变了config.yaml字段变了但本地旧的挂载文件还在导致新旧配置混在一起启动时报一些莫名奇妙的错。我的建议是升级前先备份整个docker目录和.env文件然后在升级后主动对比新版docker-compose里sandbox服务的定义和旧版有什么差异。如果新版多了环境变量或者改了挂载路径就第一时间同步更新本地的config.yaml。docker compose pull执行后用docker compose up -d重新创建容器不要只靠旧的容器一直跑。有一次我升级后沙盒容器反复崩溃日志里没有明显报错最后发现是新版镜像要求config.yaml里必须有max_request_size_mb字段旧文件里没有。补上字段以后一切恢复正常。所以升级以后先看日志几乎所有配置问题都会暴露在日志里。4.3 最后分享两个小习惯我现在每次部署Dify环境都会固定走三步先docker compose config -q检查语法再单独把sandbox服务启动起来看日志最后再启动整套服务。这个顺序看着很简单但真的能提前拦下一大半问题。因为沙盒是Dify里最需要跟外部环境交互的组件它出问题页面上一时半会儿很难定位。另外一个习惯是生产环境千万不要图省事给沙盒容器加privileged。我知道权限问题很烦直接放开确实立竿见影但代价是沙盒保护形同虚设。我在项目里宁可把业务代码拆得更干净把系统调用需求降到最低也不愿意为了一时的方便埋下安全漏洞。后面你如果维护这套系统越久越会觉得这个选择是值得的。