如何在美国洛杉矶服务器上部署Dify并完成首次访问?
在美国洛杉矶的 Linux 服务器上部署 Dify,首次运行可以直接使用项目提供的 Docker Compose 文件。服务器运行 Dify 及其依赖服务,外部通过服务器公网 IPv4 地址访问内置网关;第一次验收的重点是容器能够稳定启动、管理页面可以打开,并能完成管理员初始化。

下面以 amd64 架构的 Ubuntu 22.04 或 Ubuntu 24.04 为例,先通过公网 IP 完成首次访问,再说明域名和 HTTPS 的切换方式。Dify 版本应选择仓库中已经核对过的发布标签,不能把未确认的版本号直接用于生产环境。
面向美国用户部署 Dify,A5idc数据提供美国物理服务器资源,涵盖常规 Xeon 与 AMD EPYC 等系列,可为容器服务、后台与数据库运行提供不同的计算和存储配置。AMD 方案中有 EPYC 4584PX 搭配 64GB DDR5、960GB NVMe,以及 EPYC 7713 搭配 128GB 内存和两块 1.92TB NVMe;常规系列另有 CN2 GIA 线路方案,为面向美国访问的应用服务提供部署资源。
一、准备服务器与访问条件
1. 核对操作系统和资源
首次部署不建议在已经运行多个 Web 服务、数据库或其他容器的生产主机上直接操作。Dify 的 Compose 配置会启动多个依赖服务,内存和磁盘消耗明显高于单个应用容器。
可以先执行以下命令:
uname -m
cat /etc/os-release
free -h
df -h /
适合首次验证的参考条件如下:
| 项目 | 建议条件 | 核对重点 |
|---|---|---|
| CPU 架构 | amd64,即 x86_64 | 确认镜像兼容性 |
| 操作系统 | Ubuntu 22.04 LTS 或 Ubuntu 24.04 LTS | 避免使用生命周期临近结束的系统 |
| CPU 与内存 | 2 vCPU/4 GB 可用于小规模验证,4 vCPU/8 GB 更有余量 | 容器启动期间需要额外内存 |
| 磁盘 | SSD,建议预留 50 GB 或更多 | 镜像、数据库、上传文件和日志都会占用空间 |
| 网络 | 公网 IPv4,允许服务器主动访问代码仓库和镜像仓库 | 首次启动需要下载镜像 |
| 登录权限 | 可以使用 sudo 的普通用户 | 不建议长期直接使用 root 运行日常操作 |
如果 uname -m 返回 x86_64,操作系统显示 Ubuntu 22.04 或 24.04,且 / 分区仍有足够可用空间,就可以继续。
Dify 本身不要求洛杉矶服务器使用特定时区。建议保持服务器使用 UTC,并确认系统时间已经同步:
timedatectl status
输出中应能看到时间同步已启用或已同步。时间偏差可能导致日志排序异常、令牌校验失败或 HTTPS 证书检查异常。
2. 配置云防火墙和主机防火墙
在服务器商的安全组或云防火墙中,至少确认以下端口的入站规则:
- SSH 管理端口,例如
22/tcp,最好只允许管理端 IP; 80/tcp,用于首次 HTTP 访问;443/tcp,为后续 HTTPS 访问预留。
如果服务器使用 UFW,先查看当前状态:
sudo ufw status verbose
如果 UFW 尚未启用,不要在没有确认 SSH 规则的情况下直接执行启用操作。远程启用防火墙前,应先放行实际使用的 SSH 端口,并保持当前 SSH 会话不关闭。
示例规则如下,其中 22 必须替换为服务器实际 SSH 端口:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status numbered
确认规则无误后,再按照服务器现有安全策略启用 UFW。若要回滚本次新增的规则,只删除明确由本次部署添加的规则,不要删除其他业务使用的端口:
sudo ufw delete allow 80/tcp
sudo ufw delete allow 443/tcp
3. 检查端口是否被占用
Dify 的内置网关通常需要使用 80 和 443 端口。启动前先检查:
sudo ss -lntp | grep -E ':(80|443)\b' || true
没有输出通常表示端口空闲。如果看到 nginx、apache2、其他容器或应用已经占用端口,不要直接停止它们。应先确认现有服务用途,并决定是复用已有网关、调整 Dify 映射端口,还是更换部署主机。
二、安装 Docker 与 Compose 插件
1. 安装 Docker 软件包
以下命令适用于 Ubuntu 22.04 和 Ubuntu 24.04:
sudo apt-get update
sudo apt-get install -y ca-certificates curl git openssl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
. /etc/os-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
验证 Docker 服务和 Compose 插件:
sudo systemctl is-active docker
docker --version
docker compose version
预期结果是 Docker 服务返回 active,并能看到 Docker 客户端版本和 Compose v2 版本。
如果当前用户执行 docker 时提示没有权限,可以将当前用户加入 Docker 用户组:
sudo usermod -aG docker "$USER"
执行后退出 SSH 并重新登录,或者开启一个新的登录会话。不要在权限未生效时混用普通用户的 docker compose 和 root 用户的 sudo docker compose,否则可能出现文件所有者、配置路径和容器卷权限不一致。
三、获取 Dify 并创建配置文件
1. 选择 Dify 版本
首次部署应尽量固定一个明确的发布标签,便于后续复现和回滚。先查询仓库中的标签:
git ls-remote --tags --refs https://github.com/langgenius/dify.git | tail -n 20
从输出中选择一个已经核对过的发布标签。下面的 vX.Y.Z 只是占位示例,不能原样使用。
sudo install -d -o "$USER" -g "$USER" /opt/dify
# 将 vX.Y.Z 替换为上一步确认过的实际发布标签
DIFY_TAG='vX.Y.Z'
git clone --depth 1 --branch "$DIFY_TAG" \
https://github.com/langgenius/dify.git /opt/dify
如果 /opt/dify 已经存在文件,不要直接重复执行 git clone。先检查之前的部署是否已经创建了配置文件或数据目录:
find /opt/dify -maxdepth 2 -type f | head -n 30
确认代码版本和 Compose 文件存在:
cd /opt/dify
git describe --tags --always
test -f docker/docker-compose.yaml && echo "docker-compose.yaml found"
2. 创建环境文件并设置密钥
Dify 的 Docker 部署配置通常位于 docker 目录。先复制模板:
cd /opt/dify/docker
cp .env.example .env
查看当前版本模板中包含哪些访问地址和端口字段:
grep -E '^(CONSOLE_API_URL|CONSOLE_WEB_URL|SERVICE_API_URL|APP_API_URL|APP_WEB_URL|FILES_URL|NGINX_PORT|NGINX_SSL_PORT|EXPOSE_NGINX_PORT|EXPOSE_NGINX_SSL_PORT)=' .env || true
首次通过公网 IP 访问时,如果这些 URL 字段在模板中为空,通常可以先保持为空,不要自行添加版本中没有的配置项。端口字段则以当前 .env.example 的默认值为准。
必须为当前部署生成独立的 SECRET_KEY。不要在多台服务器之间重复使用同一个密钥,也不要把密钥提交到 Git 仓库:
if ! grep -q '^SECRET_KEY=' .env; then
echo "当前 Dify 模板没有 SECRET_KEY 字段,请先按该版本配置说明处理。" >&2
exit 1
fi
NEW_SECRET_KEY="$(openssl rand -hex 32)"
sed -i "s|^SECRET_KEY=.*|SECRET_KEY=${NEW_SECRET_KEY}|" .env
unset NEW_SECRET_KEY
chmod 600 .env
检查配置文件是否可读,但不要把完整 .env 内容粘贴到工单、聊天窗口或公开日志中:
test -r .env && test "$(stat -c '%a' .env)" = "600" && echo ".env permissions are correct"
3. 确认 Docker Compose 配置
在启动前先让 Compose 解析配置:
cd /opt/dify/docker
docker compose config -q
没有错误输出表示 YAML、环境变量和服务引用基本通过解析。如果出现变量未设置、文件不存在或端口格式错误,应先修复后再启动。不要用随机值填充未知配置项,也不要直接覆盖整个 .env,因为不同 Dify 版本的变量集合可能不同。
四、启动 Dify 服务
1. 拉取镜像并启动容器
确认服务器能够访问代码和镜像仓库后,执行:
cd /opt/dify/docker
docker compose pull
docker compose up -d
首次拉取镜像时,耗时取决于服务器出口网络、镜像大小和磁盘速度。启动命令返回并不代表所有依赖服务已经完成初始化,需要继续查看状态。
docker compose ps
docker compose ps --all
重点观察以下情况:
- 关键服务处于
Up状态; - 带健康检查的服务显示
healthy; - 没有服务持续处于
Restarting或Exited; - 容器端口映射与预期一致。
查看服务列表和最近日志:
docker compose config --services
docker compose logs --tail=100
不同 Dify 版本的服务名称可能存在差异,因此不要凭记忆强行指定服务名。需要单独查看日志时,先用 docker compose config --services 获取当前版本实际服务名称。
2. 在服务器本机验证 HTTP
先绕过外部网络,从服务器内部访问 80 端口:
curl --max-time 10 -sS -o /dev/null -w 'HTTP %{http_code}\n' \
http://127.0.0.1/
通常可以接受的结果是 HTTP 200,或者跳转场景下的 HTTP 301、HTTP 302。同时检查监听状态:
sudo ss -lntp | grep -E ':(80|443)\b' || true
如果本机请求成功,但外部浏览器访问超时,问题通常位于云安全组、UFW、DNS 或公网地址,而不是 Dify 容器内部。如果本机请求也失败,则继续查看 Compose 状态和日志。
五、完成首次访问
1. 使用公网 IP 打开管理页面
在浏览器中访问:
http://服务器公网IPv4地址/
首次初始化时,页面可能显示安装向导、管理员创建页面或登录页面,具体路径取决于部署版本。
- 如果出现管理员初始化页面,使用专门的管理员邮箱和高强度密码完成创建;
- 如果直接出现登录页,说明当前数据卷可能已经初始化过,应使用原有管理员凭据;
- 如果页面能打开但出现 502,先检查后端容器健康状态;
- 如果浏览器提示连接超时或拒绝连接,回到本机
curl和防火墙检查。
首次访问只需要验证管理控制台能够加载、管理员能够登录、页面中的基础请求不再持续报错。模型供应商密钥、知识库导入、应用发布和业务数据迁移不属于首次页面访问的必要条件,不建议在 HTTP 临时地址上录入真实业务密钥。
2. 使用域名访问
如果准备长期使用,建议将域名的 A 记录指向洛杉矶服务器公网 IPv4。先从服务器检查 DNS 是否已经解析到正确地址:

getent ahostsv4 dify.example.com
只有确认解析结果正确后,才修改 Dify 的访问地址。不同版本的 .env.example 可能使用不同字段,常见字段的用途如下:
| 配置字段 | 用途 |
|---|---|
CONSOLE_WEB_URL | 管理控制台的浏览器访问地址 |
CONSOLE_API_URL | 管理控制台使用的 API 地址 |
SERVICE_API_URL | 服务端 API 地址 |
APP_WEB_URL | 应用页面地址 |
APP_API_URL | 应用 API 地址,部分版本使用 |
FILES_URL | 文件访问地址 |
只修改当前版本模板中实际存在的字段。若所有入口都由同一个 Dify 网关提供,可以按实际域名设置为同一主机名;如果模板已经带有路径,应保留其路径结构。
在证书已经配置并确认可以使用 HTTPS 之前,不要把地址从 http:// 改成 https://。修改 .env 后,需要让 Compose 重新创建受影响的容器:
cd /opt/dify/docker
docker compose config -q
docker compose up -d
docker compose ps
首次验证可以使用公网 IP,正式使用则应在 HTTPS、生效域名和访问控制完成后再录入真实模型密钥或业务数据。
六、常见异常与处理顺序
1. 浏览器超时或连接被拒绝
按由外到内的顺序检查:

sudo ss -lntp | grep -E ':(80|443)\b' || true
curl --max-time 10 -sS -o /dev/null -w 'HTTP %{http_code}\n' \
http://127.0.0.1/
docker compose ps
判断方式如下:
- 本机
curl成功,外部访问失败:检查云安全组、UFW、访问的公网 IP 和 DNS; - 本机
curl失败,但容器没有运行:检查docker compose ps和启动日志; - 80 端口被其他服务占用:不要直接停止未知服务,应调整部署方案;
- 只有 443 失败:首次 HTTP 验证可以先使用 80,HTTPS 配置另行检查。
2. 页面出现 502 Bad Gateway
502 通常表示网关容器已经接收到请求,但后端服务尚未就绪或无法连接。先查看当前服务名和日志:
cd /opt/dify/docker
docker compose config --services
docker compose ps
docker compose logs --tail=120
如果只有少数服务仍在初始化,可以等待一段时间后再次检查。若某个容器反复重启,应重点查看该服务最后几十行日志。不要因为出现 502 就执行 docker compose down -v,这个命令可能删除当前 Compose 项目的命名数据卷。
3. 容器反复重启或服务器内存不足
检查内存、容器消耗和内核是否记录了 OOM:
free -h
docker stats --no-stream
dmesg -T | grep -i -E 'oom|out of memory' || true
如果内存不足,应优先增加服务器内存或减少同机其他服务。磁盘空间也需要同时检查:
df -h /
docker system df
不要在没有确认影响范围的情况下执行 docker system prune。该命令可能删除其他项目不再使用的镜像、容器或缓存,回滚前应先确认服务器上没有依赖这些对象的其他部署。
4. 修改 URL 后页面空白或接口报错
先确认修改的字段确实属于当前 Dify 版本:
cd /opt/dify/docker
grep -E '^(CONSOLE_API_URL|CONSOLE_WEB_URL|SERVICE_API_URL|APP_API_URL|APP_WEB_URL|FILES_URL)=' .env || true
docker compose config -q
docker compose ps
常见原因包括:
- 把还没有证书的
https://地址写入环境变量; - 域名尚未解析到当前服务器;
- 只修改了网页地址,没有同步当前版本需要的 API 地址;
- 修改
.env后只执行了docker compose restart,容器没有重新读取环境变量。
配置变更后优先执行 docker compose up -d,而不是只执行 restart。
5. 镜像下载失败
先检查域名解析和 HTTPS 出口:
getent hosts github.com
getent hosts registry-1.docker.io
curl -I --max-time 10 https://github.com
如果这些命令失败,说明服务器到代码仓库或镜像仓库的出口网络存在问题。此时应先处理服务器 DNS、出口策略或云网络配置,不要随意更换未经验证的镜像地址。
七、验收与回滚检查项
1. 首次部署验收
可以按照以下清单完成验收:
- [ ]
uname -m返回x86_64,操作系统版本符合部署前提; - [ ]
docker --version和docker compose version均能正常返回; - [ ]
docker compose config -q无错误; - [ ]
docker compose ps中没有持续Restarting或Exited的核心服务; - [ ] 服务器本机访问
http://127.0.0.1/能返回 200 或合理跳转; - [ ] 云安全组和主机防火墙已放行实际使用的端口;
- [ ] 浏览器通过公网 IP 打开 Dify 页面;
- [ ] 管理员初始化或登录流程能够完成;
- [ ] 登录后刷新页面,控制台仍能正常加载;
- [ ]
df -h /显示磁盘仍有足够余量; - [ ]
docker stats --no-stream未发现持续异常的内存增长。
如果需要验证容器重启后的数据持久性,可以在已经完成管理员初始化后执行:
cd /opt/dify/docker
docker compose restart
docker compose ps
等待服务恢复后再次刷新管理页面。该操作会造成短暂不可用,但不会主动删除命名数据卷。
2. 回滚前先保护配置和数据
回滚前至少保存当前环境文件,并记录代码版本:

cd /opt/dify/docker
BACKUP_FILE="$HOME/dify.env.$(date +%Y%m%d%H%M%S).bak"
cp -p .env "$BACKUP_FILE"
chmod 600 "$BACKUP_FILE"
cd /opt/dify
git rev-parse --short HEAD
如果已经完成管理员初始化或写入业务数据,还应先创建云磁盘快照或按照当前 Dify 版本的方式备份数据库、文件存储和向量数据。没有数据备份时,不要把版本降级作为第一处理方式,因为新版本可能已经执行数据库结构迁移。
3. 配置错误的回滚
如果问题只是环境变量修改错误,可以恢复之前的 .env 备份:
cd /opt/dify/docker
cp "$HOME/dify.env.备份时间戳.bak" .env
chmod 600 .env
docker compose config -q
docker compose up -d
上面的备份文件名需要替换成实际生成的文件名。恢复后重新检查页面、日志和容器状态。
4. 代码版本的回滚边界
如果尚未完成数据库迁移,且已经准备好旧版本标签,可以停止当前容器并切换代码版本:
cd /opt/dify/docker
docker compose down
cd /opt/dify
git checkout "$OLD_DIFY_TAG"
cd /opt/dify/docker
docker compose config -q
docker compose up -d
docker compose down 会停止并移除当前容器和网络,但不应加上 -v。docker compose down -v 会删除该 Compose 项目关联的命名数据卷,只有在确认数据完全可丢弃、已经完成备份并明确需要清空环境时才能使用。对于已经发生数据库迁移的部署,优先恢复数据库和文件快照,再根据对应版本重新启动,不要直接强行降级应用镜像。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9310.html



