解决OneTimeSecret项目Docker部署中manifest.json缺失问题

问题背景

在使用Docker Compose部署OneTimeSecret项目时，开发者遇到了前端资源加载失败的问题。具体表现为系统提示manifest.json文件未找到，并建议运行pnpm run build命令。这一问题影响了前后端的正常通信，导致前端资源请求返回404错误。

问题分析

从日志中可以观察到几个关键现象：

1. 系统报错明确指出/app/public/web/dist/.vite/manifest.json文件缺失
2. 前端资源请求（如CSS、JS和字体文件）均返回404状态码
3. 项目使用了Vite作为前端构建工具
4. Docker容器中挂载了本地目录到容器内的/app路径

深入分析后发现，问题的根源在于前端资源构建流程未正确执行。OneTimeSecret项目采用了现代前端开发工具链，需要先构建生成静态资源才能正常运行。

解决方案

方案一：本地构建前端资源

在宿主机上执行以下命令构建前端资源：

pnpm run build:local

这个命令会执行以下操作：

1. 运行类型检查
2. 使用Vite构建工具生成生产环境的前端资源
3. 创建包含资源哈希的manifest.json文件
4. 将构建产物输出到public/web/dist目录

方案二：容器内构建

如果需要在Docker容器内构建，可以使用：

pnpm run build

需要注意的是，容器内构建缺少本地开发配置（vite.config.local.ts），因此可能需要进行适当调整。

文件权限问题

构建完成后，还需要确保Docker容器能够访问这些文件。检查以下方面：

1. 构建产物是否生成在正确目录
2. 文件权限是否允许容器进程读取
3. 挂载的卷配置是否正确

Docker Compose配置注意事项

在Docker Compose配置中，特别需要注意volumes挂载的设置：

volumes:
  - .:/app

这种配置会将宿主机当前目录完全映射到容器内的/app目录，可能导致以下问题：

1. 覆盖容器内已存在的文件
2. 权限问题导致容器无法访问某些文件
3. 开发环境和生产环境文件混合

建议的解决方案：

1. 明确指定需要挂载的目录
2. 确保构建过程在正确的环境下执行
3. 检查挂载后的文件权限

最佳实践建议

1. 构建分离：建议在宿主机上完成前端构建，再将构建产物包含到Docker镜像中
2. 环境区分：明确区分开发环境和生产环境的构建配置
3. 权限管理：确保Docker容器用户有足够的权限访问所需文件
4. 日志监控：密切关注应用日志，及时发现资源加载问题
5. 缓存利用：合理配置构建缓存，提高重复构建效率

总结

OneTimeSecret项目的Docker部署问题主要源于前端资源构建流程的执行时机和环境配置。通过正确执行构建命令、合理配置Docker挂载卷以及检查文件权限，可以有效解决manifest.json缺失和资源加载404的问题。

对于类似的全栈项目部署，关键在于理解整个应用的构建和运行流程，确保每个环节的输出符合下一环节的输入要求。特别是在容器化部署场景下，更需要关注环境一致性、文件路径和权限等细节问题。