Dify默认端口修改全攻略（含API配置）
Dify 默认端口修改全攻略（含 API 配置）
在部署 AI 应用开发平台时，端口冲突几乎是每个开发者都会遇到的“第一道坎”。特别是像 Dify 这类基于 Docker Compose 构建的全栈系统，默认使用80和443端口提供 Web 服务，而这两个端口往往早已被 Nginx、Apache 或其他 Web 服务器占用。
更麻烦的是，即使你成功把页面跑起来，API 调用却依然失败——原因往往是前端不知道后端已经换了新家，还在往:80发请求。跨域错误、301 重定向、回调地址缺失……问题接踵而至。
别急。本文将带你从容器映射、环境变量到前后端通信机制，一步步彻底解决 Dify 的端口变更问题。不仅让你能访问界面，更要确保所有 API 接口、OAuth 回调、分享链接都能正常工作。
修改容器端口映射：从 docker-compose.yaml 入手
Dify 使用docker-compose.yaml来定义服务之间的依赖和网络配置，其中最关键的就是 Nginx 反向代理对外暴露的端口。
进入部署目录：
cd ./dify/docker编辑配置文件：
vi docker-compose.yaml找到nginx服务下的ports配置段：
services: nginx: image: nginx:alpine ports: - '${EXPOSE_NGINX_PORT:-80}:${NGINX_PORT:-80}' - '${EXPOSE_NGINX_SSL_PORT:-443}:${NGINX_SSL_PORT:-443}' depends_on: - web - api这里的语法是${VAR_NAME:-default}，表示如果环境变量未设置，则使用默认值。左侧为宿主机端口（外部访问用），右侧为容器内部端口。
假设你想把 HTTP 访问改为806，HTTPS 改为4436，只需修改左侧部分：
ports: - '${EXPOSE_NGINX_PORT:-806}:${NGINX_PORT:-80}' - '${EXPOSE_NGINX_SSL_PORT:-4436}:${NGINX_SSL_PORT:-443}'⚠️ 注意事项：
- 容器内 Nginx 仍然监听
80和443，这是其默认行为，无需更改。- 只需调整宿主机映射端口即可，避免因改动容器内部端口导致服务间通信异常。
- 若你确实需要容器也监听非标准端口，请同步修改
.env中的NGINX_PORT和NGINX_SSL_PORT。
保存退出后，这一步只是“告诉 Docker 把哪个端口映出来”，但真正的控制权还在.env文件手里。
环境变量驱动：.env 文件才是核心开关
Dify 的运行逻辑高度依赖.env文件，它决定了服务如何启动、绑定在哪、叫什么名字。
确保你在./dify/docker目录下执行：
vi .env设置暴露端口
查找以下两项并更新：
EXPOSE_NGINX_PORT=806 EXPOSE_NGINX_SSL_PORT=4436这两项必须与docker-compose.yaml中${EXPOSE_...}的 fallback 值一致，否则会被忽略。
✅ 实践建议：始终明确写出这些变量，不要依赖默认值。这样便于迁移和团队协作。
（可选）调整容器内部监听端口
除非有特殊需求，一般不建议修改：
NGINX_PORT=80 NGINX_SSL_PORT=443如果你改了这里，就必须同步修改docker-compose.yaml中冒号右边的部分，例如：
- '806:81'同时还要确认 Nginx 配置是否支持新端口，否则容器可能无法启动。
所以——保持默认最安全。
绑定域名或 IP 地址
为了让服务知道“我是谁”，需要设置：
NGINX_SERVER_NAME=localhost你可以替换为你的公网 IP 或域名：
NGINX_SERVER_NAME=192.168.1.100 # 或 NGINX_SERVER_NAME=mydify.example.com这个值会影响 SSL 证书生成、虚拟主机匹配等场景。
暂时关闭 HTTPS 强制跳转
调试阶段强烈建议关闭 HTTPS：
NGINX_HTTPS_ENABLED=false否则即使你访问http://localhost:806，也可能被自动跳转到https://localhost，进而触发连接拒绝或证书错误。
等一切稳定后再开启 HTTPS 并配置证书也不迟。
关键一步：更新前后端通信地址
很多人以为改完端口就万事大吉，结果发现登录接口返回 301、API 文档显示的是http://localhost、OAuth 回调地址丢了端口号……
根本原因在于：前端并不知道后端搬了家。
Dify 的前端应用（Web UI）需要通过几个关键环境变量来确定后端服务的真实位置。这些变量不会自动推导端口，必须手动填写完整 URL。
在.env文件中定位并修改以下三项：
SERVICE_API_URL=http://localhost:806 APP_API_URL=http://localhost:806 APP_WEB_URL=http://localhost:806各参数作用详解：
| 参数 | 用途说明 |
|---|---|
SERVICE_API_URL | 显示在「开发者模式」中的 API 根路径，供第三方集成参考 |
APP_API_URL | 前端发起 AJAX 请求的实际目标地址 |
APP_WEB_URL | 用户访问的 Web 应用地址，用于生成 OAuth 回调、邀请链接、H5 分享页等 |
💡 如果你启用了 HTTPS，并希望通过
4436提供加密服务，则应写为：
SERVICE_API_URL=https://api.dify.example.com:4436 APP_API_URL=https://api.dify.example.com:4436 APP_WEB_URL=https://app.dify.example.com:4436但在本地测试时，统一使用http://localhost:806最省心，避免自签名证书带来的浏览器警告。
为什么不能留空？
有些文档说“留空则自动继承当前域名”，但这只适用于同源场景。当你通过非标准端口访问时，前端 JavaScript 获取的window.location是带端口的，而后端返回的 API 地址却是无端口的localhost，这就造成了跨域请求。
明确指定带端口的完整 URL，才能保证前后端“说同一种语言”。
重启服务并验证配置生效
任何配置变更都必须通过重启容器才能加载。Docker Compose 不会热重载.env文件。
执行以下命令：
# 停止并移除现有容器 docker-compose down # 重新构建并后台启动 docker-compose up -d等待约 1–2 分钟，待所有服务初始化完成。
打开浏览器访问：
http://localhost:806你应该能看到 Dify 的登录页面。如果出现空白或报错，先检查容器状态：
docker ps | grep nginx docker logs nginx接着验证 API 是否正常工作：
访问 OpenAPI 文档页：
http://localhost:806/docs查看任意接口的 base path，确认是否为：
http://localhost:806/api/v1/而不是http://localhost/api/v1/。
也可以用 curl 测试健康检查接口：
curl http://localhost:806/health预期返回：
{"status": "ok"}再打开浏览器开发者工具，切换到 Network 面板，尝试登录或加载应用列表，观察是否有 404、502 或 CORS 错误。
特别注意/api/v1/auths/password/login这类接口，若返回 301 到http://localhost，说明APP_API_URL未正确设置。
常见问题排查指南
❌ 页面无法访问，提示“连接被拒绝”
可能原因：
- 端口未正确映射
- 防火墙拦截
- Docker 服务异常
排查步骤：
1. 检查docker-compose.yaml和.env中EXPOSE_NGINX_PORT是否一致
2. 查看 Nginx 容器是否运行：
docker ps | grep nginx- 检查宿主机是否监听对应端口：
netstat -tulnp | grep :806- 开放防火墙端口（以 CentOS/RHEL 为例）：
firewall-cmd --add-port=806/tcp --permanent firewall-cmd --reloadUbuntu 用户可用 ufw：
ufw allow 806/tcp❌ API 返回 404 或自动跳转到 :80
典型现象：
- 请求/api/v1/apps被重定向到http://localhost/api/v1/apps
- OpenAPI 页面 base URL 缺少端口号
根本原因：SERVICE_API_URL、APP_API_URL、APP_WEB_URL未设置或为空字符串
解决方案：
务必在.env中显式写出完整地址：
SERVICE_API_URL=http://localhost:806 APP_API_URL=http://localhost:806 APP_WEB_URL=http://localhost:806然后必须执行docker-compose down && up -d，仅重启容器不够，因为环境变量是在创建时注入的。
❌ 强制跳转 HTTPS，访问失败
表现形式：
访问http://localhost:806自动跳转到https://localhost，连接失败
原因分析：.env中设置了：
NGINX_HTTPS_ENABLED=true且 Nginx 配置中包含return 301 https://...规则。
临时解决方法：
关闭 HTTPS 强制跳转：
NGINX_HTTPS_ENABLED=false重启服务后重试。
🛠️ 生产环境启用 HTTPS 时，建议配合真实域名和 Let’s Encrypt 证书，而非裸 IP + 自签证书。
❌ OAuth 登录失败，回调地址错误
典型场景：
GitHub / Google 登录时提示：“Redirect URI mismatch”
问题根源：
回调地址生成为http://localhost/callback，但实际应为http://localhost:806/callback
修复方式：
确保APP_WEB_URL包含端口号：
APP_WEB_URL=http://localhost:806该地址会被用于构造所有外部回调链接，包括第三方认证、邮件邀请、H5 分享等。
小结：一次改对，长期受益
修改 Dify 的默认端口看似简单，实则涉及三层配置联动：
- 容器映射层：通过
docker-compose.yaml将宿主机端口映射到容器 - 环境控制层：由
.env文件决定实际暴露的端口和服务名称 - 通信协议层：前端依赖
APP_API_URL等变量发起正确请求
只有三者协同一致，才能实现真正可用的定制化部署。
总结操作清单：
- ✅ 修改
docker-compose.yaml中的宿主机端口映射 - ✅ 在
.env中设置EXPOSE_NGINX_PORT=806 - ✅ 明确配置
SERVICE_API_URL、APP_API_URL、APP_WEB_URL为带端口的完整 URL - ✅ 执行
docker-compose down && up -d重建容器 - ✅ 清理浏览器缓存，使用无痕模式验证功能
📌 建议将修改后的
.env文件备份归档，未来迁移、集群部署或 CI/CD 流水线中可直接复用，避免重复踩坑。
Dify 正在成为企业级 AI 应用开发的核心工具之一，无论是智能客服、知识库问答还是自动化内容生成，掌握其底层部署细节，尤其是网络与 API 配置，是你从“会用”走向“精通”的必经之路。
项目地址：https://github.com/langgenius/dify
官方文档：https://docs.dify.ai
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考