tag(修复):修复跨域错误

.env.example

@@ -6,10 +6,20 @@ LIVEKIT_API_KEY=devkey
 LIVEKIT_API_SECRET=replace-with-a-long-random-secret
 LIVEKIT_PUBLIC_URL=ws://localhost:7880
 
+# Address on which the application-server gateway listens. Set this server's
+# private IP where possible, then allow only the external Nginx server in the firewall.
+GATEWAY_BIND_ADDRESS=0.0.0.0
+
 AUTH_JWT_ISSUER=screen-share-api
 AUTH_JWT_AUDIENCE=screen-share-web
 AUTH_JWT_REALM=screen-share
 AUTH_JWT_SECRET=replace-with-a-different-long-random-secret
+# Comma-separated browser origins allowed to call the API. For a local package,
+# use http://localhost:8081; for production, use https://your-domain.
+CORS_ALLOWED_ORIGINS=http://localhost:8081
 BOOTSTRAP_ADMIN_USERNAME=admin
 BOOTSTRAP_ADMIN_PASSWORD=change-this-admin-password
 BOOTSTRAP_ADMIN_DISPLAY_NAME=管理员
+
+# Docker image tag to run; set this to the imported release version on a server.
+SCREENSHARE_VERSION=latest

.gitignore

@@ -50,3 +50,6 @@ infra/caddy/certs/
 !.vscode/extensions.json
 .DS_Store
 Thumbs.db
+
+# Release archives generated for offline server deployment
+release/

apps/ScreenShareApi/.dockerignore

@@ -0,0 +1,6 @@
+.gradle
+build/*
+!build/install/
+!build/install/**
+.env
+*.iml

apps/ScreenShareApi/Dockerfile

@@ -1,18 +1,8 @@
-FROM eclipse-temurin:21-jdk AS build
-WORKDIR /app
-
-COPY gradlew gradlew
-COPY gradle gradle
-COPY build.gradle.kts settings.gradle.kts gradle.properties ./
-RUN chmod +x gradlew
-RUN ./gradlew dependencies --no-daemon
-
-COPY src src
-RUN ./gradlew installDist --no-daemon
-
 FROM eclipse-temurin:21-jre
 WORKDIR /app
-COPY --from=build /app/build/install/ScreenShareApi ./
+
+# package-release.sh creates this distribution before building the image.
+COPY build/install/ScreenShareApi ./
 
 EXPOSE 8080
 ENTRYPOINT ["./bin/ScreenShareApi"]

apps/ScreenShareApi/gradle/wrapper/gradle-wrapper.properties

@@ -1,9 +1,9 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.1-bin.zip
-networkTimeout=10000
+networkTimeout=120000
-retries=0
+retries=3
-retryBackOffMs=500
+retryBackOffMs=1000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

apps/ScreenShareApi/src/main/kotlin/Routing.kt

@@ -34,14 +34,17 @@ fun Application.configureRouting() {
         }
     }
     install(CORS) {
-        val configuredOrigins = this@configureRouting.environment.config
+        val configuredOrigins = (
-            .propertyOrNull("cors.allowedOrigins")
+            this@configureRouting.environment.config.propertyOrNull("cors.allowedOrigins")
                 ?.getString()
-            ?.split(",")
+                ?: System.getenv("CORS_ALLOWED_ORIGINS")
+                ?: "http://localhost:5173"
+            )
+            .split(",")
             ?.map(String::trim)
             ?.filter(String::isNotEmpty)
             .orEmpty()
-        configuredOrigins.ifEmpty { listOf("http://localhost:5173") }.forEach { origin ->
+        configuredOrigins.forEach { origin ->
             allowHost(
                 host = origin.removePrefix("http://").removePrefix("https://"),
                 schemes = listOf(if (origin.startsWith("https://")) "https" else "http"),

apps/ScreenShareApi/src/test/kotlin/ServerTest.kt

@@ -3,7 +3,6 @@ package top.OrangeRoll
 import io.ktor.client.request.get
 import io.ktor.http.HttpStatusCode
 import io.ktor.server.testing.testApplication
-import configureRouting
 import kotlin.test.*
 
 class ServerTest {

apps/ScreenShareWeb/Dockerfile

@@ -1,9 +0,0 @@
-FROM node:22-alpine
-WORKDIR /app
-
-COPY package.json package-lock.json ./
-RUN npm ci
-COPY . .
-
-EXPOSE 5173
-CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]

apps/ScreenShareWeb/src/App.css

@@ -269,6 +269,85 @@ button:disabled {
   margin-left: 0;
 }
 
+.modal-backdrop {
+  position: fixed;
+  z-index: 20;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 20px;
+  background: rgb(16 17 27 / 58%);
+}
+
+.share-settings-modal {
+  width: min(520px, 100%);
+  padding: 22px;
+  border-radius: 16px;
+  background: #fff;
+  box-shadow: 0 22px 70px rgb(0 0 0 / 30%);
+}
+
+.modal-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 20px;
+}
+
+.modal-heading h2 {
+  margin: 0;
+}
+
+.icon-button {
+  min-height: 32px;
+  padding: 0 10px;
+  background: transparent;
+  color: #4c4e65;
+  font-size: 1.6rem;
+  font-weight: 400;
+}
+
+.settings-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 14px;
+}
+
+.codec-setting {
+  grid-column: 1 / -1;
+}
+
+.codec-description {
+  min-height: 2.8em;
+  color: #686b82;
+  font-size: 0.79rem;
+  font-weight: 400;
+  line-height: 1.45;
+}
+
+.audio-setting {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 18px;
+  font-size: 0.88rem;
+}
+
+.audio-setting input[type='checkbox'] {
+  width: 17px;
+  min-height: 17px;
+}
+
+.settings-note {
+  margin: 16px 0;
+  color: #686b82;
+  font-size: 0.83rem;
+}
+
+.modal-confirm {
+  width: 100%;
+}
+
 .screen-stage {
   display: grid;
   min-height: min(72vh, 760px);
@@ -278,6 +357,14 @@ button:disabled {
   background: #10111b;
 }
 
+.screen-stage:fullscreen {
+  width: 100vw;
+  height: 100vh;
+  min-height: 100vh;
+  border: 0;
+  border-radius: 0;
+}
+
 .screen-stage .screen-frame {
   display: grid;
   grid-template-rows: auto minmax(0, 1fr);
@@ -370,4 +457,8 @@ button:disabled {
   .screen-thumbnail {
     flex-basis: 170px;
   }
+
+  .settings-grid {
+    grid-template-columns: 1fr;
+  }
 }

apps/ScreenShareWeb/src/App.tsx

@@ -24,8 +24,54 @@ type TokenResponse = {
 
 type ScreenFeed = { id: string; track: Track; label: string; isLocal: boolean }
 type RoomHistoryItem = { id: string; title: string; visitedAt: string }
+type ShareResolution = '1280x720' | '1920x1080' | '2560x1440' | '3840x2160'
+type VideoCodec = 'vp8' | 'h264' | 'vp9' | 'av1' | 'h265'
 
 const ROOM_HISTORY_KEY = 'screen-share-room-history'
+const SHARE_SETTINGS_KEY = 'screen-share-share-settings'
+const SHARE_RESOLUTIONS: Record<ShareResolution, { width: number; height: number }> = {
+  '1280x720': { width: 1280, height: 720 },
+  '1920x1080': { width: 1920, height: 1080 },
+  '2560x1440': { width: 2560, height: 1440 },
+  '3840x2160': { width: 3840, height: 2160 },
+}
+const VIDEO_CODECS: Record<VideoCodec, { label: string; description: string }> = {
+  vp8: {
+    label: 'VP8（推荐兼容性）',
+    description: '编解码兼容性最好、CPU 压力较低；压缩效率一般，适合跨浏览器和稳定内网场景。',
+  },
+  h264: {
+    label: 'H.264（硬件支持优先）',
+    description: '多数设备具备硬件编解码，企业设备和 Safari 兼容性较好；文字/桌面内容压缩效率通常不如 VP9、AV1。',
+  },
+  vp9: {
+    label: 'VP9（清晰度与带宽平衡）',
+    description: '对文字和静态桌面内容压缩更高效，可降低带宽；编码/解码 CPU 消耗更高，老旧设备兼容性较弱。',
+  },
+  av1: {
+    label: 'AV1（最高压缩效率）',
+    description: '低带宽下画质通常最好；编解码计算开销最高，需要较新的浏览器与硬件支持。',
+  },
+  h265: {
+    label: 'H.265 / HEVC（实验性）',
+    description: '压缩效率高，部分 Apple/硬件环境支持良好；浏览器和 WebRTC 互通性有限，建议只在受控设备环境使用。',
+  },
+}
+
+type SavedShareSettings = {
+  resolution?: ShareResolution
+  frameRate?: number
+  codec?: VideoCodec
+  audio?: boolean
+}
+
+function readShareSettings(): SavedShareSettings {
+  try {
+    return JSON.parse(localStorage.getItem(SHARE_SETTINGS_KEY) ?? '{}') as SavedShareSettings
+  } catch {
+    return {}
+  }
+}
 
 function ScreenTrack({ track, label, variant = 'main' }: ScreenFeed & { variant?: 'main' | 'thumbnail' }) {
   const mediaContainerRef = useRef<HTMLDivElement>(null)
@@ -71,6 +117,7 @@ async function apiRequest<T>(path: string, options: RequestInit = {}, token?: st
 
 function App() {
   const roomRef = useRef<Room | null>(null)
+  const screenStageRef = useRef<HTMLElement>(null)
   const [session, setSession] = useState<Session | null>(null)
   const [authMode, setAuthMode] = useState<'login' | 'register'>('login')
   const [username, setUsername] = useState('')
@@ -93,6 +140,21 @@ function App() {
   const [localScreen, setLocalScreen] = useState<ScreenFeed | null>(null)
   const [remoteScreens, setRemoteScreens] = useState<ScreenFeed[]>([])
   const [activeScreenId, setActiveScreenId] = useState<string | null>(null)
+  const [fullscreenMode, setFullscreenMode] = useState<'none' | 'page' | 'stage'>('none')
+  const [showShareSettings, setShowShareSettings] = useState(false)
+  const [shareResolution, setShareResolution] = useState<ShareResolution>(() => {
+    const value = readShareSettings().resolution
+    return value && value in SHARE_RESOLUTIONS ? value : '1920x1080'
+  })
+  const [shareFrameRate, setShareFrameRate] = useState(() => {
+    const value = readShareSettings().frameRate
+    return value && [15, 24, 30, 48, 60].includes(value) ? value : 30
+  })
+  const [shareCodec, setShareCodec] = useState<VideoCodec>(() => {
+    const value = readShareSettings().codec
+    return value && value in VIDEO_CODECS ? value : 'vp8'
+  })
+  const [shareAudio, setShareAudio] = useState(() => readShareSettings().audio ?? false)
   const [createdInvite, setCreatedInvite] = useState('')
   const [error, setError] = useState('')
 
@@ -109,6 +171,32 @@ function App() {
     void roomRef.current?.disconnect()
   }, [])
 
+  useEffect(() => {
+    localStorage.setItem(
+      SHARE_SETTINGS_KEY,
+      JSON.stringify({
+        resolution: shareResolution,
+        frameRate: shareFrameRate,
+        codec: shareCodec,
+        audio: shareAudio,
+      }),
+    )
+  }, [shareResolution, shareFrameRate, shareCodec, shareAudio])
+
+  useEffect(() => {
+    function syncFullscreenMode() {
+      if (document.fullscreenElement === screenStageRef.current) {
+        setFullscreenMode('stage')
+      } else if (document.fullscreenElement === document.documentElement) {
+        setFullscreenMode('page')
+      } else {
+        setFullscreenMode('none')
+      }
+    }
+    document.addEventListener('fullscreenchange', syncFullscreenMode)
+    return () => document.removeEventListener('fullscreenchange', syncFullscreenMode)
+  }, [])
+
   function saveSession(next: Session) {
     localStorage.setItem('screen-share-session', JSON.stringify(next))
     setSession(next)
@@ -278,7 +366,20 @@ function App() {
   async function toggleScreenShare() {
     if (!roomRef.current) return
     try {
-      await roomRef.current.localParticipant.setScreenShareEnabled(!isSharing)
+      if (isSharing) {
+        await roomRef.current.localParticipant.setScreenShareEnabled(false)
+      } else {
+        const options = {
+          audio: shareAudio,
+          resolution: { ...SHARE_RESOLUTIONS[shareResolution], frameRate: shareFrameRate },
+        }
+        const needsVp8Backup = shareCodec === 'vp9' || shareCodec === 'av1' || shareCodec === 'h265'
+        await roomRef.current.localParticipant.setScreenShareEnabled(true, options, {
+          videoCodec: shareCodec,
+          backupCodec: needsVp8Backup ? { codec: 'vp8' } : false,
+          degradationPreference: 'maintain-resolution',
+        })
+      }
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : '无法切换屏幕共享')
     }
@@ -289,6 +390,31 @@ function App() {
     roomRef.current = null
   }
 
+  async function togglePageFullscreen() {
+    try {
+      if (fullscreenMode === 'page') {
+        await document.exitFullscreen()
+      } else {
+        await document.documentElement.requestFullscreen()
+      }
+    } catch {
+      setError('浏览器不允许进入全屏模式。')
+    }
+  }
+
+  async function toggleStageFullscreen() {
+    if (!screenStageRef.current) return
+    try {
+      if (fullscreenMode === 'stage') {
+        await document.exitFullscreen()
+      } else {
+        await screenStageRef.current.requestFullscreen()
+      }
+    } catch {
+      setError('浏览器不允许将主画面全屏显示。')
+    }
+  }
+
   function logout() {
     leaveRoom()
     localStorage.removeItem('screen-share-session')
@@ -382,11 +508,69 @@ function App() {
       {connected && (
         <>
           <section className="room-toolbar" aria-label="房间控制">
-            {canShare && <button type="button" className="share-button" onClick={() => void toggleScreenShare()}>{isSharing ? '停止共享屏幕' : '共享屏幕'}</button>}
+            <button type="button" className="secondary" onClick={() => void togglePageFullscreen()}>
+              {fullscreenMode === 'page' ? '退出网页全屏' : '网页全屏'}
+            </button>
+            <button type="button" className="secondary" onClick={() => void toggleStageFullscreen()} disabled={!activeScreen}>
+              {fullscreenMode === 'stage' ? '退出全屏显示' : '全屏显示'}
+            </button>
+            {canShare && (
+              <>
+                <button type="button" className="secondary" onClick={() => setShowShareSettings((visible) => !visible)}>
+                  共享设置
+                </button>
+                <button type="button" className="share-button" onClick={() => void toggleScreenShare()}>{isSharing ? '停止共享屏幕' : '共享屏幕'}</button>
+              </>
+            )}
             <button type="button" className="secondary" onClick={leaveRoom}>离开房间</button>
           </section>
 
-          <section className="screen-stage">
+          {canShare && showShareSettings && (
+            <div className="modal-backdrop" role="presentation" onMouseDown={() => setShowShareSettings(false)}>
+              <section className="share-settings-modal" role="dialog" aria-modal="true" aria-labelledby="share-settings-title" onMouseDown={(event) => event.stopPropagation()}>
+                <div className="modal-heading">
+                  <h2 id="share-settings-title">共享屏幕设置</h2>
+                  <button type="button" className="icon-button" aria-label="关闭" onClick={() => setShowShareSettings(false)}>×</button>
+                </div>
+                <div className="settings-grid">
+                  <label className="codec-setting">
+                    视频编码/解码
+                    <select value={shareCodec} onChange={(event) => setShareCodec(event.target.value as VideoCodec)} disabled={isSharing}>
+                      {Object.entries(VIDEO_CODECS).map(([codec, details]) => <option key={codec} value={codec}>{details.label}</option>)}
+                    </select>
+                    <span className="codec-description">{VIDEO_CODECS[shareCodec].description}</span>
+                  </label>
+                  <label>
+                    分辨率
+                    <select value={shareResolution} onChange={(event) => setShareResolution(event.target.value as ShareResolution)} disabled={isSharing}>
+                      <option value="1280x720">1280 × 720（720p）</option>
+                      <option value="1920x1080">1920 × 1080（1080p）</option>
+                      <option value="2560x1440">2560 × 1440（2K）</option>
+                      <option value="3840x2160">3840 × 2160（4K）</option>
+                    </select>
+                  </label>
+                  <label>
+                    帧率
+                    <select value={shareFrameRate} onChange={(event) => setShareFrameRate(Number(event.target.value))} disabled={isSharing}>
+                      <option value={15}>15 FPS</option>
+                      <option value={24}>24 FPS</option>
+                      <option value={30}>30 FPS</option>
+                      <option value={48}>48 FPS</option>
+                      <option value={60}>60 FPS</option>
+                    </select>
+                  </label>
+                </div>
+                <label className="audio-setting">
+                  <input type="checkbox" checked={shareAudio} onChange={(event) => setShareAudio(event.target.checked)} disabled={isSharing} />
+                  共享系统音频（需在浏览器选择框中确认）
+                </label>
+                <p className="settings-note">{isSharing ? '停止共享后可修改，设置会在下次共享时生效。' : '高级 Codec 会附带 VP8 兼容备份流；最终能否使用仍取决于发布端和观看端的浏览器解码能力。'}</p>
+                <button type="button" className="primary modal-confirm" onClick={() => setShowShareSettings(false)}>保存设置</button>
+              </section>
+            </div>
+          )}
+
+          <section className="screen-stage" ref={screenStageRef}>
             {activeScreen
               ? <ScreenTrack {...activeScreen} variant="main" />
               : <p className="empty stage-empty">等待参与者共享屏幕</p>}

docker-compose.yml

@@ -6,7 +6,7 @@ services:
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
     ports:
-      - "5432:5432"
+      - "127.0.0.1:5432:5432"
     volumes:
       - postgres-data:/var/lib/postgresql/data
     healthcheck:
@@ -23,11 +23,12 @@ services:
     environment:
       LIVEKIT_KEYS: "${LIVEKIT_API_KEY}: ${LIVEKIT_API_SECRET}"
     ports:
-      - "7880:7880"
+      - "127.0.0.1:7880:7880"
       - "7881:7881"
       - "50000-50100:50000-50100/udp"
 
   api:
+    image: screenshare-api:${SCREENSHARE_VERSION:-latest}
     build:
       context: ./apps/ScreenShareApi
     env_file: .env
@@ -43,6 +44,7 @@ services:
       AUTH_JWT_AUDIENCE: ${AUTH_JWT_AUDIENCE}
       AUTH_JWT_REALM: ${AUTH_JWT_REALM}
       AUTH_JWT_SECRET: ${AUTH_JWT_SECRET}
+      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-http://localhost:5173}
       BOOTSTRAP_ADMIN_USERNAME: ${BOOTSTRAP_ADMIN_USERNAME}
       BOOTSTRAP_ADMIN_PASSWORD: ${BOOTSTRAP_ADMIN_PASSWORD}
       BOOTSTRAP_ADMIN_DISPLAY_NAME: ${BOOTSTRAP_ADMIN_DISPLAY_NAME}
@@ -52,17 +54,19 @@ services:
       postgres:
         condition: service_healthy
     ports:
-      - "8080:8080"
+      - "127.0.0.1:8080:8080"
 
-  web:
+  gateway:
-    build:
+    image: nginx:1.27-alpine
-      context: ./apps/ScreenShareWeb
-    environment:
-      VITE_API_PROXY_TARGET: http://api:8080
     depends_on:
       - api
+      - livekit
+    volumes:
+      - ./web:/usr/share/nginx/html:ro
+      - ./infra/nginx/gateway.conf:/etc/nginx/conf.d/default.conf:ro
     ports:
-      - "5173:5173"
+      # The external Nginx server connects to this port over the private network.
+      - "${GATEWAY_BIND_ADDRESS:-0.0.0.0}:8081:80"
 
 volumes:
   postgres-data:

docs/SERVER_DEPLOYMENT.md

@@ -0,0 +1,141 @@
+# 服务器离线部署与配置
+
+此文档适用于服务器已有 Nginx 的场景。部署包不包含 .env，因为其中存放数据库密码、JWT Secret、LiveKit Secret 和初始管理员密码。
+
+## 1. 在构建机生成部署包
+
+构建机需要 Docker、JDK 21 和 Node.js/npm。脚本先在宿主机执行 Gradle 和 npm 构建；前端 `dist` 放入部署包的 `web` 目录，由应用服务器的 Gateway Nginx 容器托管。外部 Nginx 只需反代 Gateway 的一个地址。
+
+~~~bash
+cd /path/to/ScreenShare
+chmod +x scripts/package-release.sh
+./scripts/package-release.sh 0.1.0
+~~~
+
+生成文件：
+
+~~~text
+release/screen-share-0.1.0.tar.gz
+~~~
+
+若当前账户没有 Docker socket 权限，脚本会仅对 Docker 命令自动调用 `sudo`。不要使用 `sudo ./scripts/package-release.sh`，这样 Gradle/npm 才能使用当前用户已经下载的依赖缓存。
+
+脚本默认使用本项目开发机 IntelliJ 下载的 JDK 21：`/home/orangeroll/.jdks/ms-21.0.12`，无需手动设置 `JAVA_HOME`。换电脑或升级 JDK 时，直接修改 `scripts/package-release.sh` 顶部的 `project_java_home` 路径。
+
+### Docker 代理
+
+Docker daemon 不会自动使用桌面或终端的系统代理。若构建机缺少 API、PostgreSQL、LiveKit 或 Nginx 镜像且访问 Docker Hub 较慢，先为 Docker daemon 配置 HTTP/HTTPS 代理。下面以本机 HTTP 代理端口 7890 为例；如果使用 Clash 等工具，应填写 HTTP 代理端口，不是 SOCKS 端口。已有本地镜像会被脚本直接复用。
+
+~~~bash
+sudo systemctl edit docker
+~~~
+
+写入：
+
+~~~ini
+[Service]
+Environment="HTTP_PROXY=http://127.0.0.1:7890"
+Environment="HTTPS_PROXY=http://127.0.0.1:7890"
+Environment="NO_PROXY=localhost,127.0.0.1,::1,postgres,api,livekit"
+~~~
+
+然后执行：
+
+~~~bash
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+sudo docker info | grep -i proxy
+~~~
+
+重启 Docker 会短暂影响运行中的容器。Gradle/npm 现在在宿主机运行，直接使用当前用户的网络和本地缓存；Docker daemon 代理只负责拉取基础镜像。
+
+~~~bash
+./scripts/package-release.sh 0.1.0
+~~~
+
+不要把 SOCKS 代理端口直接填入 Docker daemon 配置。
+
+## 2. 传输并导入服务器
+
+服务器需要 Docker Compose，但不需要访问镜像仓库。
+
+~~~bash
+scp release/screen-share-0.1.0.tar.gz deploy@your-server:/opt/
+ssh deploy@your-server
+cd /opt
+tar -xzf screen-share-0.1.0.tar.gz
+cd screen-share-0.1.0
+sudo docker load -i images.tar
+~~~
+
+## 3. 创建服务器 .env
+
+~~~bash
+cp .env.example .env
+chmod 600 .env
+~~~
+
+必须修改下列值，且不要提交或传回 Git：
+
+~~~dotenv
+POSTGRES_PASSWORD=替换为随机数据库密码
+LIVEKIT_API_KEY=生产环境Key
+LIVEKIT_API_SECRET=替换为随机LiveKit密钥
+LIVEKIT_PUBLIC_URL=wss://share.example.com
+GATEWAY_BIND_ADDRESS=应用服务器内网IP
+AUTH_JWT_SECRET=替换为随机JWT密钥
+CORS_ALLOWED_ORIGINS=https://share.example.com
+BOOTSTRAP_ADMIN_PASSWORD=替换为强管理员密码
+SCREENSHARE_VERSION=0.1.0
+~~~
+
+`GATEWAY_BIND_ADDRESS` 推荐填应用服务器的内网 IP。也可暂时保留默认 `0.0.0.0`，但必须在应用服务器防火墙中只允许外部 Nginx 服务器访问 `8081/TCP`。
+
+## 4. 配置外部 Nginx
+
+部署包内的 `gateway` 服务负责静态前端、`/api/` 与 LiveKit 信令；外部 Nginx 只需要一个上游地址。复制 `infra/nginx/screenshare.conf.example` 的 server 配置到外部 Nginx 站点，将 `share.example.com`、证书路径和 `10.0.0.20:8081` 改为真实值。`map` 指令只能在 `http` 块中声明一次。
+
+外部 Nginx 不需要复制 `web` 目录，也不需要分别配置 `/api/`、`/rtc/` 或 `/twirp/`。
+
+验证并重载：
+
+~~~bash
+sudo nginx -t
+sudo systemctl reload nginx
+~~~
+
+## 5. 启动服务
+
+~~~bash
+sudo docker compose --env-file .env up -d
+sudo docker compose ps
+sudo docker compose logs -f api
+~~~
+
+首次 API 启动会执行 Flyway 迁移并创建 bootstrap 管理员。浏览器访问 https://share.example.com。
+
+## 6. 防火墙与安全组
+
+应用服务器开放：
+
+~~~text
+TCP 8081（仅允许外部 Nginx 的内网 IP）
+TCP 7881（浏览器直接访问 LiveKit 的 TCP 兜底）
+UDP 50000-50100
+~~~
+
+外部 Nginx 服务器向公网开放 TCP `80, 443`。不要公开 PostgreSQL `5432`、API `8080` 或 LiveKit HTTP/WebSocket `7880`；它们只供 Docker 内部 Gateway 使用。
+
+浏览器的 WebRTC 媒体不会经过任一 Nginx，仍须直连应用服务器的 LiveKit `7881/TCP` 和 `50000-50100/UDP`。生产环境还需要在 LiveKit 中正确声明公网 IP/NAT。
+
+## 7. 更新版本
+
+在构建机用新版本号重新打包，例如 0.1.1。服务器上导入新 images.tar，修改 .env 中 SCREENSHARE_VERSION，再重建服务：
+
+~~~bash
+sudo docker load -i images.tar
+sed -i 's/^SCREENSHARE_VERSION=.*/SCREENSHARE_VERSION=0.1.1/' .env
+sudo docker compose --env-file .env up -d
+~~~
+
+PostgreSQL 卷会保留；Flyway 会自动执行新增迁移。数据库升级前建议备份卷或执行 pg_dump。

infra/nginx/gateway.conf

@@ -0,0 +1,37 @@
+server {
+    listen 80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        # React single-page application fallback.
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api/ {
+        proxy_pass http://api:8080;
+        # The API is reachable only through this same-origin gateway. Do not
+        # forward the browser Origin header while legacy API images allow only
+        # the Vite development origin.
+        proxy_set_header Origin "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
+    }
+
+    location /rtc/ {
+        proxy_pass http://livekit:7880;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 3600s;
+    }
+
+    location /twirp/ {
+        proxy_pass http://livekit:7880;
+        proxy_set_header Host $host;
+    }
+}

infra/nginx/screenshare.conf.example

@@ -0,0 +1,33 @@
+# External Nginx configuration. Put the map block in nginx.conf's http {}
+# section only once. Replace 10.0.0.20 with the application server's private IP.
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 80;
+    server_name share.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name share.example.com;
+
+    # Replace with your existing certificate paths.
+    ssl_certificate     /etc/letsencrypt/live/share.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/share.example.com/privkey.pem;
+
+    location / {
+        # This one upstream handles the frontend, API, and LiveKit signalling.
+        proxy_pass http://10.0.0.20:8081;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_read_timeout 3600s;
+    }
+}

scripts/package-release.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+version="${1:-}"
+if [[ -z "$version" ]]; then
+  echo "Usage: $0 <version>"
+  exit 1
+fi
+
+# 修改此处为本机 JDK 21 的实际安装目录。
+project_java_home="/home/orangeroll/.jdks/ms-21.0.12"
+if [[ ! -x "$project_java_home/bin/java" ]]; then
+  echo "Java 21 was not found at: $project_java_home"
+  echo "Update project_java_home in scripts/package-release.sh."
+  exit 1
+fi
+
+export JAVA_HOME="$project_java_home"
+export PATH="$JAVA_HOME/bin:$PATH"
+echo "Using Java: $JAVA_HOME"
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "npm was not found. Install Node.js/npm before packaging."
+  exit 1
+fi
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+project_dir="$(cd "$script_dir/.." && pwd)"
+release_dir="$project_dir/release"
+bundle_dir="$release_dir/screen-share-$version"
+archive="$release_dir/screen-share-$version.tar.gz"
+
+if ! mkdir -p "$release_dir" || [[ ! -w "$release_dir" ]]; then
+  echo "Release directory is not writable: $release_dir"
+  echo "Fix it once with: sudo chown -R \$USER:\$USER \"$release_dir\""
+  exit 1
+fi
+
+if docker info >/dev/null 2>&1; then
+  docker_command=(docker)
+else
+  docker_command=(sudo docker)
+fi
+
+run_docker() {
+  "${docker_command[@]}" "$@"
+}
+
+ensure_docker_image() {
+  local image="$1"
+  if run_docker image inspect "$image" >/dev/null 2>&1; then
+    echo "Using local Docker image: $image"
+  else
+    retry run_docker pull "$image"
+  fi
+}
+
+if [[ -e "$bundle_dir" || -e "$archive" ]]; then
+  if [[ -d "$bundle_dir" && ! -e "$archive" ]] && [[ -z "$(find "$bundle_dir" -type f -print -quit)" ]]; then
+    find "$bundle_dir" -depth -type d -empty -delete
+  else
+    echo "Release already exists: $bundle_dir or $archive"
+    exit 1
+  fi
+fi
+
+retry() {
+  local attempt
+  for attempt in 1 2 3; do
+    if "$@"; then
+      return 0
+    fi
+    if [[ "$attempt" -lt 3 ]]; then
+      echo "Command failed; retrying in 5 seconds ($attempt/3)..."
+      sleep 5
+    fi
+  done
+  return 1
+}
+
+docker_build() {
+  local build_args=()
+  local network_args=()
+  local proxy_enabled=false
+  local variable
+  local value
+  local build_network="${DOCKER_BUILD_NETWORK-}"
+  for variable in HTTP_PROXY HTTPS_PROXY NO_PROXY http_proxy https_proxy no_proxy; do
+    value="${!variable-}"
+    if [[ -n "$value" ]]; then
+      build_args+=(--build-arg "$variable=$value")
+      proxy_enabled=true
+    fi
+  done
+  if [[ "$proxy_enabled" == true ]]; then
+    echo "Using proxy environment variables for Docker build containers."
+  fi
+  if [[ -n "$build_network" ]]; then
+    network_args=(--network "$build_network")
+    echo "Using Docker build network: $build_network"
+  fi
+  run_docker build "${build_args[@]}" "${network_args[@]}" "$@"
+}
+
+build_api_distribution() {
+  (
+    cd "$project_dir/apps/ScreenShareApi"
+    ./gradlew installDist --no-daemon
+  )
+}
+
+build_web_assets() {
+  (
+    cd "$project_dir/apps/ScreenShareWeb"
+    npm run build
+  )
+}
+
+build_api_distribution
+build_web_assets
+retry docker_build -t "screenshare-api:$version" "$project_dir/apps/ScreenShareApi"
+ensure_docker_image postgres:16-alpine
+ensure_docker_image livekit/livekit-server:v1.9.10
+ensure_docker_image nginx:1.27-alpine
+
+mkdir -p "$bundle_dir/infra/livekit" "$bundle_dir/infra/nginx" "$bundle_dir/docs" "$bundle_dir/web"
+
+run_docker save \
+  "screenshare-api:$version" \
+  postgres:16-alpine \
+  livekit/livekit-server:v1.9.10 \
+  nginx:1.27-alpine \
+  > "$bundle_dir/images.tar"
+
+cp -a "$project_dir/apps/ScreenShareWeb/dist/." "$bundle_dir/web/"
+cp "$project_dir/docker-compose.yml" "$bundle_dir/"
+cp "$project_dir/.env.example" "$bundle_dir/"
+cp "$project_dir/infra/livekit/livekit.yaml" "$bundle_dir/infra/livekit/"
+cp "$project_dir/infra/nginx/gateway.conf" "$bundle_dir/infra/nginx/"
+cp "$project_dir/infra/nginx/screenshare.conf.example" "$bundle_dir/infra/nginx/"
+cp "$project_dir/docs/SERVER_DEPLOYMENT.md" "$bundle_dir/docs/"
+
+cat > "$bundle_dir/RELEASE_VERSION" <<EOF
+$version
+EOF
+
+tar -C "$release_dir" -czf "$archive" "screen-share-$version"
+echo "Created offline deployment archive: $archive"