Feature/docker deployment

[mmarzl17]

add relevant files for Docker deployment and fix bugs in the front-end code

[houhyh]

您好！感谢您提交 Docker 配置及 Dockerfile 相关 PR。我们在合并前做了一轮预检查，发现有几处实现细节可能会影响容器的稳定性、可用性以及构建体验。为了降低后续线上运行和排查成本，麻烦您再帮忙 review 并调整一下以下问题：

一、Docker 配置相关

1. docker-entrypoint.sh 中进程启动方式需要调整

目前脚本中存在类似 exec uvicorn ... & 的写法。这里 exec 的语义是替换当前进程，而 & 表示后台运行，两者组合使用语义上不太一致。

从实际运行效果看，可能会导致后续的 nginx 启动命令无法正常执行，从而造成容器启动后前端服务不可用。建议重新梳理 uvicorn 与 nginx 的启动方式，确保两个服务都能按预期启动。

2. nginx 与 uvicorn 的启动时序建议增加保障

当前配置下，nginx 可能会在 uvicorn 尚未完成初始化时就开始接收请求。在这段短暂窗口期内，访问 /api/ 的请求可能会出现 502。

建议在启动流程中增加等待或健康检查机制，确保后端服务就绪后再对外提供完整服务，从而减少启动阶段的偶发错误。

3. 后台进程异常处理建议增强

当前如果将 uvicorn 放到后台运行，set -e 对该后台进程的异常捕获能力有限。若 uvicorn 启动失败，容器可能不会及时退出，而是继续保持运行状态。

这种情况下，前端页面可能仍能正常加载，但 API 请求会持续返回 502，同时缺少明确的退出信号或错误提示，后续排查成本会比较高。建议补充后台进程的状态检测、日志输出或失败退出机制。

---

二、Dockerfile 相关

4. apt-get 安装后建议清理缓存

目前 Dockerfile 中执行 apt-get install 后，似乎还没有清理 APT 缓存。虽然不影响功能，但会使最终镜像体积有所增加。

建议在安装完成后增加缓存清理逻辑，例如清理 /var/lib/apt/lists/*，以优化镜像大小。

5. 生产镜像中建议移除 EXPOSE 5173

当前 Dockerfile 中包含 EXPOSE 5173。考虑到生产环境下前端静态资源是由 nginx 通过 80 端口提供服务，5173 通常是 Vite dev server 使用的开发端口。

建议生产 Dockerfile 中仅暴露实际对外服务端口，避免造成使用者对运行端口的误解。

---

三、镜像源配置支持

当前 Dockerfile 中 pip 和 npm 安装流程暂未提供镜像源参数支持。在部分网络环境下，尤其是国内网络环境中，构建过程可能会因为访问官方源超时而失败。

建议为 APT、pip、npm 三类包管理器都增加 --build-arg 支持，允许使用者在构建时自行传入镜像地址。同时，默认值仍建议保持为官方源，以兼顾通用性和可配置性。

例如可以考虑支持以下构建参数：

ARG APT_MIRROR=官方默认源
ARG PIP_INDEX_URL=官方默认源
ARG NPM_REGISTRY=官方默认源

这样既不会影响默认构建行为，也能方便不同网络环境下的用户按需配置。

---

整体来看，这些问题主要集中在容器启动流程的健壮性、生产镜像的规范性以及构建环境的适配性上。麻烦您根据上述建议再做一轮调整，调整完成后我们再继续推进合并流程。

Hi, thank you for submitting the PR for the Docker configuration and Dockerfile updates.

Before merging, we performed a preliminary review and noticed a few areas that may affect container stability, runtime availability, and the build experience in certain network environments. Could you please take another look and make the necessary adjustments?

1. Docker Configuration

1.1 docker-entrypoint.sh: process startup behavior

In docker-entrypoint.sh, the current usage appears to combine exec uvicorn ... with &.

Since exec replaces the current process, while & runs a command in the background, using them together can lead to unexpected behavior. In practice, this may prevent the subsequent nginx startup command from being executed, causing the frontend service to be unavailable after the container starts.

Please consider revisiting the startup logic to ensure both uvicorn and nginx are started as expected.

1.2 Startup order between nginx and uvicorn

At the moment, nginx may start accepting requests before uvicorn has fully initialized.

During this short startup window, requests to /api/ may return 502 responses. It would be helpful to add a readiness check, wait mechanism, or another form of startup coordination to ensure the backend is ready before API traffic is routed to it.

1.3 Error handling for background processes

If uvicorn is started as a background process, set -e may not reliably catch failures from that process.

As a result, if uvicorn fails to start, the container may continue running silently. The frontend could still load normally, but all API requests would return 502, without a clear failure signal or container exit, making the issue difficult to troubleshoot.

Please consider adding proper process monitoring, error handling, or exit behavior so backend startup failures can be detected promptly.

---

2. Dockerfile

2.1 APT cache cleanup

The Dockerfile currently appears to run apt-get install without cleaning up the APT cache afterward.

While this does not affect functionality, it may unnecessarily increase the final image size. Please consider cleaning up files such as /var/lib/apt/lists/* after package installation.

2.2 EXPOSE 5173 in the production image

The Dockerfile currently includes EXPOSE 5173.

Since the production image serves the frontend through nginx on port 80, and 5173 is typically used by the Vite development server, exposing this port in the production Dockerfile may be misleading.

Please consider removing EXPOSE 5173 and exposing only the actual production service port.

---

3. Support for Configurable Package Mirrors

The current Dockerfile does not seem to provide configurable mirror support for pip or npm installation. In some network environments, especially where access to official registries is slow or unreliable, the build may fail due to timeouts.

To improve build reliability and flexibility, please consider adding --build-arg support for APT, pip, and npm mirrors, while keeping the official sources as the default values.

For example, the Dockerfile could support build arguments such as:

ARG APT_MIRROR=<official default>
ARG PIP_INDEX_URL=<official default>
ARG NPM_REGISTRY=<official default>

This would preserve the default behavior while allowing users to specify alternative mirrors when needed.

---

Overall, these items are mainly related to startup robustness, production image cleanliness, and build configurability. Please review and update the PR accordingly so we can continue moving it toward merge.