如何在美国洛杉矶服务器上部署Dify并完成首次访问?

发布人:A5数据发布时间:2026-11-14 09:50阅读量:33

在美国洛杉矶的 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

相关推荐