fix(deploy): defer nginx upstream DNS until api is reachable

Co-authored-by: Cursor <cursoragent@cursor.com>

docker/nginx/admin.conf

@@ -4,11 +4,14 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    resolver 127.0.0.11 valid=10s ipv6=off;
+
     gzip on;
     gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
 
     location /api/ {
-        proxy_pass http://api:3000;
+        set $api_upstream api:3000;
+        proxy_pass http://$api_upstream;
         proxy_http_version 1.1;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;

docker/nginx/player.conf

@@ -4,11 +4,15 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    # Docker 内置 DNS；避免 api 未就绪时启动失败
+    resolver 127.0.0.11 valid=10s ipv6=off;
+
     gzip on;
     gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
 
     location /api/ {
-        proxy_pass http://api:3000;
+        set $api_upstream api:3000;
+        proxy_pass http://$api_upstream;
         proxy_http_version 1.1;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -17,7 +21,8 @@ server {
     }
 
     location /uploads/ {
-        proxy_pass http://api:3000;
+        set $api_upstream api:3000;
+        proxy_pass http://$api_upstream;
         proxy_http_version 1.1;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;

docs/项目启动指南.md

@@ -540,9 +540,13 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
 - 已改为 entrypoint 执行 `node dist/infrastructure/database/seed-cli.js`；拉代码后重建 api 镜像
 - **临时绕过**（先让 API 起来）：`.env.docker` 设 `SEED_DATABASE=false` 后 `up -d api`
 
----
+### 14. player/admin 重启，`host not found in upstream "api"`
 
-## 十、推荐日常开发顺序
+- 原因：nginx 启动时 API 容器尚未就绪，静态 `proxy_pass http://api:3000` 解析失败
+- 已改为 Docker DNS + 变量延迟解析；重建 player/admin 镜像
+- **临时处理**（API 已 Up 时）：`docker compose ... restart player`
+
+---
 
 ```text
 1. docker compose up -d