从Devbox到公网：entrypoint.sh、nginx代理与CORS允许源配置全解析-代码聚汇网

代码在本地跑起来的时候，大家都觉得项目已经完事了，但真正到了“发版上线”这一步，才会意识到AI帮你生成的只是业务代码，部署链路里还有一堆环境问题等着你填坑。这一节标题里有三样东西——entrypoint.sh、nginx代理、允许源，看起来是三个独立名词，实际上是同一个问题的三个侧面：怎么让一个跑在Devbox容器里的应用，被外面的用户稳定访问到。这篇就完整梳理当时的部署过程和踩坑记录。

1. 发版上线要解决的三件事：先把部署链路想清楚

1.1 为什么AI生成代码不等于项目能上线

用DeepSeek辅助写代码，配合Cursor的AI编程能力，把一整个项目的功能逻辑搭出来，这个过程对于现在的开发者来说已经不算难了。难的是发版上线这一步：你会发现代码能跑、接口能通、页面能开，但这一切只存在于本地环境或者Devbox的开发端口里，完全没有进入“可被公网稳定访问”的状态。

零代码或者AI辅助开发的项目有一个通病——使用者在业务逻辑上投入了大量精力，反而忽略了部署环境需要什么样的人为准备。AI可以帮你生成一份数据库表结构、一套后端接口、一个前端页面，但它不知道你的运行环境是什么、你的域名入口在哪、你的服务需不需要跨域放行。这些东西恰恰是发版上线时最容易卡住人的地方。

放在Devbox这个场景里，问题会更具体。Devbox是一种容器化的开发运行环境，它给了你一个类似真实Linux服务器的空间，你可以在里面安装依赖、启动服务、暴露端口。但容器环境有一个特点：它是从镜像启动的，每次启动都相当于一次“冷启动”，环境里不会自动保留你手动执行过的那些命令。如果只是手动跑一遍服务，下次容器重启就又回到原点。所以必须有一个入口脚本把这些初始化动作固化下来，这就是entrypoint.sh存在的核心原因。

1.2 Devbox、Sealos、nginx在部署链路中分别扮演什么角色

先把这个系列里几个核心工具的分工理清楚，后面讲配置才不会绕。

DeepSeek在这里承担的是大模型能力提供方的角色。往下游走，Cursor负责用AI辅助生成和修改代码；但在真正部署时，DeepSeek的价值已经不体现在代码生成上了，而是你的应用里是否要调用DeepSeek的API，比如做一个对话机器人、文档问答、内容生成类的功能。如果需要，那么在上线阶段就要保证后端服务能够稳定调用到DeepSeek接口，这个调用链路的超时设置、网络连通性都要纳入nginx和entrypoint.sh的考量。

Devbox在本系列里充当的是云端开发与运行容器。你可以理解为它是一台“带公网访问能力的开发机”，代码最终会在这个容器里跑起来。它的特点是接近生产环境，但又不像生产环境那样完全托管，很多运维细节还是需要你自己处理。

Sealos承担的是从容器到线上服务的最后一步转化。你可以把Sealos理解成一个云原生应用管理平台，它负责把Devbox中构建好的应用变成真正有公网入口的服务。不管底层有多少复杂的调度逻辑，在使用者视角上，它帮你解决的是“容器跑起来之后，怎么让用户通过一个域名访问到它”的问题。

nginx在这里是部署链路中的代理层，也是发版环节最容易出问题的一块。它的核心作用是：统一流量入口、转发请求到实际运行的服务端口、处理跨域响应头、托管静态前端资源。简单说，Devbox里跑的是业务进程，nginx是站在业务进程前面的“总闸门”，用户请求先到nginx，nginx再按规则转给背后的应用。

1.3 一条完整的上线链路和各环节的职责

当时我们把整个发版流程抽象成了一条链路，你可以对照自己的工作环境做适当调整：

本地用Cursor结合DeepSeek完成代码开发，把项目推送到Git仓库。
Devbox从Git拉取代码，准备运行环境。
Devbox容器启动时自动执行entrypoint.sh，这个脚本负责安装依赖、做初始化、构建前端资源、启动后端服务。
后端服务在Devbox的某个端口监听，比如8000。
nginx作为反向代理，监听80端口，把来自公网的请求转发到本地8000端口。
Sealos负责把nginx所在容器作为应用发布出去，并绑定公网域名。
用户通过域名访问，请求到达nginx，nginx把API请求转给后端，把页面请求交给前端静态文件。

上面第3步解决的是“服务怎么自动跑起来”，第5步解决的是“请求怎么正确转发”，第7步之前的“允许源”配置解决的是“浏览器为什么愿意放行这些请求”。三步连起来，才是一个完整的发版上线闭环。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. entrypoint.sh：把初始化动作用脚本固化下来

2.1 为什么需要entrypoint.sh而不是一条docker run命令

先讲一个容易混淆的点：entrypoint.sh是一个脚本文件，它写清楚“容器启动后要按顺序做什么”，然后由容器运行时在启动阶段自动执行它。

容器运行机制里有一个规则：一个容器只会执行一条启动命令。你可以在镜像配置里写死这条命令，也可以在使用Devbox时指定它。问题是，一个真实项目的启动从来不是一条命令能解决的，至少包含几个阶段：

检查环境变量是否齐全，比如数据库连接串、API密钥。
安装项目依赖，Python项目是pip，Node项目是npm。
执行数据库迁移或者初始化数据。
如果项目分前后端，通常还需要构建前端资源。
最后才是真正启动服务进程。

这一串动作如果靠人手动执行，第一次部署没问题，但只要容器重置、重新拉取、换环境，就又得重新敲一遍，而且很容易漏步骤。更关键的是，手动操作不具备可复现性——你在这台机器上成功了，换一台一模一样的机器很可能因为少装了一个系统包、漏设了一个环境变量而失败。

所以entrypoint.sh的本质是一个“可执行文档”。它把你发版时需要做的所有初始化动作步骤化、自动化，并且让容器每次启动都执行同样的动作，保证环境一致性。如果某次启动失败，不需要回忆上次成功时手动敲了什么，只需要看脚本在哪一步报错即可。

2.2 一份立即可用的entrypoint.sh模板

下面这份脚本来源于我们当时的项目实践，你可以直接复制改造成自己项目的版本。它主要针对的是Node.js前后端项目，如果你的后端是Python（FastAPI、Flask）或者Java，只需替换对应启动命令部分。

bash复制#!/bin/sh
set -e

echo "[entrypoint] 开始执行启动脚本，时间：$(date)"

# 1. 检查关键环境变量
if [ -z "$DATABASE_URL" ]; then
  echo "[entrypoint] 错误：环境变量 DATABASE_URL 未设置，启动终止"
  exit 1
fi

if [ -z "$DEEPSEEK_API_KEY" ]; then
  echo "[entrypoint] 警告：DEEPSEEK_API_KEY 未设置，AI 相关功能将不可用"
fi

# 2. 等待依赖服务就绪（比如数据库）
if [ -n "$DATABASE_URL" ]; then
  echo "[entrypoint] 等待数据库就绪……"
  # 从连接串中解析主机部分，这里根据实际数据库类型调整
  DB_HOST=$(echo "$DATABASE_URL" | sed -n 's/.*@\([^:/]*\).*/\1/p')
  DB_PORT=$(echo "$DATABASE_URL" | sed -n 's/.*@[^:]*:\([0-9]*\)\/.*/\1/p')
  if [ -n "$DB_HOST" ] && [ -n "$DB_PORT" ]; then
    i=1
    until (echo > "/dev/tcp/${DB_HOST}/${DB_PORT}") 2>/dev/null; do
      echo "[entrypoint] 数据库尚未就绪，等待 2 秒（第 ${i} 次尝试）……"
      sleep 2
      i=$((i + 1))
      if [ "$i" -gt 30 ]; then
        echo "[entrypoint] 错误：等待数据库超时，请检查 DATABASE_URL 配置"
        exit 1
      fi
    done
    echo "[entrypoint] 数据库连接正常"
  fi
fi

# 3. 安装后端依赖
echo "[entrypoint] 安装后端依赖……"
cd /app/backend
if [ -f "requirements.txt" ]; then
  pip install -r requirements.txt --no-cache-dir
fi
if [ -f "package.json" ]; then
  npm install --production
fi

# 4. 数据库迁移与初始化
echo "[entrypoint] 执行数据库迁移……"
if [ -f "manage.py" ]; then
  python manage.py migrate --noinput
fi
if [ -f "alembic.ini" ]; then
  alembic upgrade head
fi

# 5. 构建前端（如果存在前端目录且有package.json）
if [ -d "/app/frontend" ] && [ -f "/app/frontend/package.json" ]; then
  echo "[entrypoint] 构建前端静态资源……"
  cd /app/frontend
  npm install
  npm run build
fi

# 6. 启动后端服务
echo "[entrypoint] 启动后端服务……"
cd /app/backend

if [ -f "manage.py" ]; then
  exec python manage.py runserver 0.0.0.0:8000
elif [ -f "app.py" ]; then
  exec python app.py
else
  echo "[entrypoint] 错误：未识别的后端启动方式，请检查项目结构"
  exit 1
fi

这份脚本看起来不复杂，但有几个设计点值得展开说一下。

脚本开头写了set -e，作用是一旦某条命令执行失败，脚本立即终止，不再继续往下执行。这个很重要。如果没有它，前面依赖安装失败，脚本还是会继续执行启动命令，最终启动的是一个残缺的服务，排查起来非常困难。有了set -e，哪里失败哪里停下，日志一目了然。

等待数据库就绪那段，用了/dev/tcp做端口探测，没有任何额外依赖。实际项目中，数据库容器可能比应用容器启动慢，如果启动脚本进去就直接跑迁移，大概率会报连接失败。加一个带超时的等待循环，可以极大提高首次部署的成功率。第30次尝试后主动退出是为了避免死循环把容器搞成一直重启的状态。

环境变量检查也是很多人容易忽略的。在容器环境下，配置一般通过环境变量注入，而不是写死在代码里。如果某个关键变量没有设置，服务即使启动成功也会在运行时报错，而且报错信息往往让新手摸不着头脑。与其这样，不如在入口脚本里直接做显式检查，缺了就退出并给出明确提示。

最后一行用了exec关键字，作用是用启动服务的新进程替代当前shell进程。这个细节很多教程不会讲，但它直接影响容器停止时的表现。使用exec后，服务进程会成为容器的主进程，接收来自容器运行时的停止信号；如果不用exec直接敲启动命令，shell会挂起等待子进程退出，信号处理链路会变长，很可能导致容器停止超时。

2.3 编写entrypoint.sh时常见的四个低级错误

这些错误不是原理层面的问题，但每一个都足以让你的容器启动失败，而且排查起来非常浪费时间。

第一个是Windows下编辑脚本导致的换行符问题。如果你在Windows上用记事本或者某些默认编辑器写完entrypoint.sh再传到Linux环境，文件里每行末尾会带一个\r。Linux下执行时shell会提示类似/bin/sh^M: bad interpreter的错误。解决办法有两个：要么用VS Code这类支持切换换行符的编辑器，把右下角行尾序列改成LF；要么在Linux端执行一次sed -i 's/\r$//' entrypoint.sh清理。

第二个是忘记给脚本添加可执行权限。上传或创建脚本后，如果直接作为entrypoint执行，可能遇到权限拒绝。记得执行chmod +x entrypoint.sh。建议把这一步也写进项目文档，避免换环境后遗漏。

第三个是脚本里用了Windows风格的路径，比如\app\backend，在Linux下全部不识别。统一使用/app/backend风格路径，目录分隔符不要用反斜杠。

第四个是循环等待写成死循环。有些模板会写while true; do sleep 1; done无限等待依赖就绪，看上去很稳妥，实际上如果依赖服务永远起不来，容器就会无限重启或卡死，最终在日志里什么都看不出来。正确的做法是设置尝试次数上限和超时退出，宁可启动失败也不要无限等待。

提示：entrypoint.sh在调试阶段可以用sh -x entrypoint.sh执行，这样每条命令执行前都会打印出来，哪里出错一目了然。这是排查启动脚本问题最直接的手段。

2.4 把entrypoint.sh当作发版文档来维护

从项目上线第一天开始，我就坚持把entrypoint.sh视为“发版操作文档”而不是“临时用的启动脚本”。因为脚本里固化了这个项目在Devbox环境中启动所需的所有环节，任何环境上的特殊要求都应该在注释里写明。

比如当时我们的数据库是通过Sealos上的PostgreSQL服务提供的，连接信息通过环境变量注入，脚本里就没有硬编码任何IP和账号。又比如我们前端要用到DeepSeek的接口做AI对话，API Key通过环境变量注入，脚本里只做检查不存储密钥。这种“所有敏感信息和环境差异一律外部注入”的原则，让这套entrypoint.sh直接复用到了后续好几个项目上，基本不用大改。

每次修改脚本，记得同步更新脚本头部的注释说明，写清楚改了哪一步、为什么改。下次发版遇到问题，这份注释就是最可靠的排查线索。

3. nginx代理：给Devbox里的服务加一道“总闸门”

3.1 为什么Devbox里已经有服务了，还要加nginx

这是当时项目组里问得最多的一个问题：后端服务明明已经在Devbox里跑起来了，并且Devbox也提供了端口访问能力，为什么还要在前面再放一个nginx？

原因可以拆成几点。

第一，真实项目不止一个后端服务。除了业务后端，可能还有静态前端文件、图片资源、AI能力网关，甚至要转发到DeepSeek的API。如果让用户直接分别访问这些服务的不同端口，且不说端口暴露面太大，光是让前端记住后端接口地址就够麻烦了。nginx可以把多个服务统一收口到同一个入口，按路径规则分发到不同后端。

第二，端口和域名管理的问题。Devbox给的访问地址是带随机端口的临时地址，不适合直接对外。而nginx监听的标准80/443端口，前面的Sealos或者其他云平台也更容易把域名绑定到标准端口上。你可以把nginx理解成地址总入口，用户只需要记一个域名，剩下的分发规则全部由nginx处理。

第三，nginx在处理静态资源、日志、HTTP头、超时控制、CORS方面有天然优势。很多项目是前端SPA加后端API的结构，如果直接用后端服务托管前端页面，会有很多额外开发量。但用nginx配置一个静态目录和API反向代理，十几行配置就能解决。

3.2 一份稳妥的前后端分离nginx配置

下面是一份非常通用的nginx站点配置，覆盖了静态前端、API反向代理、一个额外指向Devbox调试端口的转发，以及必要的HTTP头设置。

nginx复制server {
    listen 80;
    server_name _;

    # 前端静态文件目录，由entrypoint.sh中构建流程生成
    root /app/frontend/dist;
    index index.html;

    # gzip压缩，对文本类资源收益明显
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    gzip_min_length 1024;

    # 请求体大小限制，上传功能按需调整
    client_max_body_size 20m;

    # 前端页面路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 后端API转发
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 流式接口时关闭缓冲
        proxy_buffering off;
        proxy_cache off;

        # 长请求超时时间，AI对话场景必须设大
        proxy_read_timeout 300s;
        proxy_connect_timeout 30s;
        proxy_send_timeout 300s;
    }

    # 单独转发到某个调试端口
    location /debug/ {
        proxy_pass http://127.0.0.1:9000/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源缓存
    location /assets/ {
        expires 7d;
        add_header Cache-Control "public";
    }
}

逐个说下几个容易出问题的配置项。

try_files $uri $uri/ /index.html;这行千万不能少。它解决的是前端history路由模式下刷新页面404的问题。如果不写这一行，用户访问/login或/dashboard时nginx会直接去查找对应的静态文件，找不到就返回404。加了这行后，当请求路径没有对应真实文件时，nginx会回退到index.html，由前端路由接管。几乎所有SPA项目都会遇到这个问题。

proxy_set_header Host $host;这行很多时候被当成固定模板抄，但实际作用很大。如果后端代码里用到了绝对路径或基于Host生成回调地址，没有正确传递Host就会生成错误链接。$host表示用用户请求原始域名传给后端，而不是用nginx配置里写的IP或端口。

proxy_http_version 1.1;和两个Upgrade头配合，是为了让nginx正确支持WebSocket和SSE这类长连接。HTTP/1.0不做连接复用，WebSocket的Upgrade流程需要HTTP/1.1支持。凡是接口涉及实时通信，这四行缺一不可。

后面那段proxy_buffering off;是当时排查AI对话流式输出问题时才补上的。如果后端接口用的是SSE（Server-Sent Events）方式逐字返回内容，nginx默认会先把响应缓冲到一定大小再一次性发给客户端，结果前端看到的效果就是长时间没有反应，内容一下子全冒出来，完全失去了流式对话的体验。关闭缓冲后，内容到达nginx立即转发，前端才能实时收到。

3.3 用nginx转发到外部API的边界意识

早期我们还做过一个尝试：在后端服务里不直接写死对DeepSeek API的调用，而是通过nginx把某个路径转发到DeepSeek的接口地址上。做法是可以做到，但这里有一个边界问题需要意识清楚。

nginx作为反向代理，通常转发的是内网或同环境内的服务地址。如果你让公网用户的请求经过你的nginx再转发到外部API，相当于把nginx当成了一个API网关使用。这带来了几个新问题：请求超时的尺度、流量计费的归属、API密钥是否要暴露在客户端请求头里。

在AI应用里，对API密钥的保护是一个安全底线。如果前端JavaScript代码里写死了DeepSeek的API Key，任何人打开浏览器的开发者工具都能直接看到并盗用。正确做法是后端服务持有API Key，前端只把用户输入传给后端，由后端统一调用DeepSeek接口再返回结果。所以对外部API的转发也应该放在后端代码层面完成，而不是暴露nginx转发地址给前端。

3.4 nginx配置文件自身的排查手段

nginx配置最让人头疼的往往是语法正确但行为不符合预期。遇到这种情况，优先用命令定位问题：

bash复制# 检查配置文件语法
nginx -t

# 重载配置
nginx -s reload

# 查看运行日志，重点关注error.log
tail -f /var/log/nginx/error.log

配置生效慢或者不生效时，先检查是不是有别的nginx进程占用了80端口。在Devbox容器里如果之前起过别的服务占了端口，nginx启动会报address already in use。处理方式是用lsof -i:80找到占用进程，停掉后再启动nginx。

另外，如果改了配置后reload了但还是旧行为，检查一下是不是改错了配置文件。nginx默认读取/etc/nginx/nginx.conf，而这个文件可能通过include引入了多个子配置文件，你要改的server块不一定在你以为的文件里。用nginx -T命令可以完整打印最终生效的全部配置，排查时先用这个确认你改的配置确实被加载了。

4. 允许源配置：跨域问题到底是谁在拦你

4.1 浏览器同源策略与报错现象

围绕“允许源”这个概念出过太多问题了。它的本质是浏览器的一个安全机制：当一个网页里的JavaScript代码尝试访问不同源（协议、域名、端口任一不同）的服务时，浏览器会拦截响应，前端控制台报出形如Access to XMLHttpRequest at 'http://xxx' from origin 'http://yyy' has been blocked by CORS policy的错误。

放到我们这套部署链路里，典型的跨域场景是这样的：前端页面运行在http://域名A上，API接口运行在http://域名B:8000上，浏览器发现两者的域名不同，就触发了同源策略。还有一种更隐蔽的场景，即使域名相同，如果前端页面是HTTPS、后端是HTTP，也会因为协议不同被视为跨域。

记住一件事：跨域限制是浏览器单方面的行为，不是服务器在拒绝你。你直接拿curl去请求后端接口，一定会拿到正常响应，因为curl没有这种安全限制。所以排查跨域问题时，先分清到底是浏览器拦截还是后端真的报错，再动手改配置，这样能省掉大量无效排查时间。

4.2 在nginx这一层统一处理CORS

解决CORS有两种常见思路。一种是在后端代码里加上跨域中间件，比如Python的Flask-CORS、Django的django-cors-headers；另一种是在nginx层统一加响应头。

考虑到零代码/AI辅助生成的项目，后端代码可能随时被AI重新生成或调整，我建议优先考虑nginx层处理。原因是，每次AI修改代码都可能覆盖掉你手写的CORS配置，而nginx配置相对独立，只要发版流程不变，配置就一直在那里。

一个最简的nginx级CORS配置片段如下：

nginx复制location /api/ {
    if ($request_method = 'OPTIONS') {
        add_header Access-Control-Allow-Origin $http_origin;
        add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
        add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Requested-With';
        add_header Access-Control-Max-Age 86400;
        return 204;
    }

    add_header Access-Control-Allow-Origin $http_origin always;
    add_header Access-Control-Allow-Credentials true always;
    add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Requested-With';

    proxy_pass http://127.0.0.1:8000;
}

重点讲几个字段。

Access-Control-Allow-Origin是用来声明允许哪些源访问接口。有两个值需要注意：*表示任何源都可以访问，但它的代价是不能再使用Access-Control-Allow-Credentials: true，也就是如果接口要携带Cookie，就不能用通配符，必须像上面这样用$http_origin动态回显请求方Origin。浏览器看到这个头里的值和自己的Origin完全一致，就会放行。用变量匹配当前请求方的来源，是最好的多域名允许方案。

Access-Control-Allow-Headers的作用是声明允许前端携带哪些自定义请求头。前端如果使用Authorization头传token，后端就必须明确允许这个头。漏掉的话会看到明明带了token，浏览器却把请求拦截，提示Request header field authorization is not allowed by Access-Control-Allow-Headers。

对于OPTIONS预检请求的处理要尤其注意。当浏览器发起非简单请求（例如带JSON内容或Authorization头的POST请求）时，会先发一个OPTIONS请求询问服务器允不允许。这里我们用return 204直接处理掉，返回204状态码就够了，不需要把这个请求转发到后端。如果没有拦截OPTIONS直接转发给后端，很多后端框架不一定能正确响应预检，最终前端看到的就是真实请求从来没有发出过，报错信息还是CORS。

always参数的作用也要说明一下。nginx中add_header指令在响应状态码是某些特定值（比如404、500）时默认不生效。加always后，不管后端返回什么状态码，CORS头都会带上。当时我们踩过一个坑：后端接口正常时跨域没有问题，一旦接口返回500，浏览器因为响应头里没有CORS信息，把真实的500错误吞掉，只显示一个让人摸不着头脑的CORS报错。加了always后，即使是错误响应也能正确携带CORS头，前端拿到真正的状态码错误信息。

4.3 本地联调与线上环境的两种允许源配置

“允许源”不只是上线后才需要考虑的问题。本地开发时，Cursor里跑的前端开发服务器通常在3000端口，Devbox里的后端在8000端口，端口不同同样产生跨域。如果没有提前处理，前端界面永远调不通接口，你会以为是AI生成的代码有bug，其实只是CORS在捣乱。

建议在工作流里保留一份“开发用宽松配置”和一份“上线用严格配置”。开发环境的允许源可以写得放宽一些，比如直接允许http://localhost:3000或者干脆先放开；上线环境的允许源则只保留你的正式域名。用nginx配置模板加上不同环境变量渲染的方式，发版时只带入这份严格配置，避免把过宽的CORS带上线。

检查CORS配置是否生效，不需要写任何前端代码，直接用curl看响应头：

bash复制curl -i -X OPTIONS http://你的域名/api/chat \
  -H "Origin: http://你的前端域名" \
  -H "Access-Control-Request-Method: POST"

如果响应头里能看到Access-Control-Allow-Origin，说明nginx已经正确补上了头，问题大概率在前端或者浏览器缓存，可以进一步排查。

5. 上线前后的实测问题库与检查清单

5.1 五个高频问题实录

代码写完、配置也按模板往上一扔，不代表就能顺利上线。整理一下这次发版前后实际踩过的问题，按“现象-排查过程-最终解决”写成速查表，你在自己项目上遇到类似情况可以直接对照。

现象	可能原因	排查与解决
容器启动后几秒就退出，日志是`no such file or directory`，且报错涉及entrypoint.sh	脚本换行符是CRLF	用`sed -i 's/\r$//' entrypoint.sh`清理换行符，再重启
启动日志停在某一步，后面没有任何输出	脚本中某条命令需要交互式确认，或者等待数据库超时	用`sh -x entrypoint.sh`查看卡在哪条命令，给对应流程加`-y`参数或超时逻辑
nginx启动报`address already in use`	容器内已有其他进程占用80端口	`lsof -i:80`找到占用进程，停掉或修改nginx监听端口
前端页面能打开，接口请求全是504	nginx连不上后端服务端口	在Devbox容器内先验证`curl http://127.0.0.1:8000`是否通，不通则后端没起来或端口不一致
接口能通但AI对话不输出，等了很久一次性全出	后端是SSE流式输出，但nginx开了缓冲	在反向代理配置中加`proxy_buffering off`，保持连接头设置

除表格外，有一个排查过程印象很深，单独拿来说。当时前端页面始终进不去，刷新直接404，第一反应是路由文件配置写错了。检查了半天才发现问题出在nginx的location /没有配try_files。前端打包出来的静态文件只有index.html一个入口文件，而用户访问的是/login这种虚拟路由路径，nginx找不到对应的物理文件自然就404了。加上try_files $uri $uri/ /index.html;，刷新问题立刻解决。

还有一个隐含问题值得提醒。正常开发时前端页面几乎不会有用户真的去刷新深层链接，所以你往往注意不到这个bug。但上线后用户收藏夹里存的、别人分享出去的，全是完整路径而不是首页。没有try_files回退机制，这些分享链接全部不可用。这个细节属于“平时不冒烟、上线就爆炸”的典型。

5.2 上线前30分钟检查清单

最后分享一份我们内部固定使用的检查清单，每次发版前过一遍，可以避免绝大多数低级的线上事故。

第一步，确认代码分支和版本。Devbox从哪个分支拉代码、本地和线上是否同一个commit，这个建议在Git仓库里写一个带日期的tag，Deploy时对着tag来。那次我们线上跑的是旧代码，查了半天配置，最后才发现Devbox拉取的是Master分支而本地改了dev分支，忽略了这个源头问题。

第二步，核对环境变量。用命令列出容器当前的全部环境变量，然后对照项目文档逐项检查。尤其关注数据库连接、API Key、回调地址这三类。环境变量出错造成的故障往往非常隐蔽，服务能启动，但功能悄悄挂掉，没有一定的排查经验很难想到源头在变量上。

第三步，检查entrypoint.sh的可执行权限和首行语法。在Devbox中执行sh -n entrypoint.sh可以快速做语法检查，不需要实际运行整个脚本。这一步很快，但能拦住低级错误。

第四步，验证nginx配置并预启动。先执行nginx -t确认配置语法，再执行nginx启动。启动后用curl -I http://127.0.0.1验证首页是否能返回200，用curl -X OPTIONS配合Origin头验证CORS响应头是否存在。

第五步，端到端冒烟测试。从用户视角走一遍完整流程：打开页面、登录、发起业务请求、验证AI相关接口的流式输出。不要只测开发环境下的“快乐路径”，至少再测一次接口返回错误时前端的表现，确保错误能正常展示而不是被CORS拦截吞掉。

第六步，检查容器重启后的自恢复能力。直接重启Devbox容器或重新部署Sealos应用，观察entrypoint.sh是否会自动完成全部初始化，服务是否自动恢复到可用状态。这一步如果跳过，等到线上半夜容器OOM重启，没人手动进容器敲命令，服务就一直挂了。

一个发版后值得长期保留的习惯

这一节操作完，项目真正跑到了公网上，整体流程才算闭环。我个人实际操作下来最大的体会是：发版顺利与否，很大程度上不取决于AI生成代码的质量，而取决于有没有把那些“初始化操作”“转发规则”“跨域头”这些运行环境细节固化成文档和配置。entrypoint.sh执行成功的瞬间，日志一行行滚出来，那种从容感远超在本地跑通代码时的兴奋。

最后再分享一个我坚持了很久的小习惯：把entrypoint.sh、nginx配置、CORS相关的说明全部放进项目的Git仓库，单独建一个deploy/目录管理，并且要求每次发版前必须查看和更新目录里的文档。因为它们就是这套系统的完整运维说明。AI技术更新很快，模型、工具、框架几个月一变，但容器启动逻辑、反向代理规则、浏览器的同源策略这些底层机制不会轻易变。把这三样搞懂了，你会发现以后不管换什么AI辅助工具、什么云容器平台，发版上线这件事都有章可循，不会每次从零踩坑。

从Devbox到公网：entrypoint.sh、nginx代理与CORS允许源配置全解析