企业官网建设流程全解析

Jonex 是一个一站式多模态解析引擎 + 本体驱动的 AI 知识引擎，把文档、图片、音视频解析为可问答、可溯源的知识服务。本文带你用 Docker Compose 五步完成 Jonex 生产级部署，覆盖 GPU 加速文档解析、HTTPS 域名接入、安全加固检查清单三大生产要点，并附上常见故障排查手册，适合运维人员与新手快速上手 🚀。

一、先理解 Jonex 的生产部署拓扑

在生产模式下，浏览器**只访问frontend-gateway（Nginx，80/443 端口）**这一个入口：

• 静态资源：Shell 壳应用 + 4 个子前端，由 Nginx 聚合分发
• /api/**：反向代理到 API Gateway → Sidecar → 各能力服务
• PostgreSQL、Redis、Milvus、Neo4j、MinIO 等中间件全部只在容器内网访问，不映射任何宿主端口

Jonex 的知识生产流水线如下，理解它有助于判断哪些组件最需要资源（如 GPU）：

完整拓扑、网络设计与持久化卷设计可参考 deploy/DEPLOYMENT_ARCHITECTURE.md，日常运维命令汇总在 deploy/README.md。

二、生产部署五步走

第 1 步：克隆仓库并初始化配置

git clone https://gitcode.com/gh_mirrors/jo/jonex cd jonex make init

make init会生成deploy/.env、deploy/.env.rag、deploy/.env.mcp及各前端.env，后续只需改实际值。

第 2 步：编辑 deploy/.env

对照 .env.example 模板，生产环境必改项：

第 3 步：构建生产镜像

make build-prod # 国内源构建（腾讯云 pip/apt、npmmirror） make build-prod USE_OVERSEAS_MIRROR=true # 国外官方源

首次构建会先打共享基础镜像jonex/python-base:local，再用 buildx 并行构建 7 个后端镜像；atomic-rag 镜像内含 MinerU、whisper 等模型（约 3-4 GB），耗时较长属正常现象。

第 4 步：启动并验证健康检查

make up-prod make ps-prod

生产模式只有 80/443 对外，验证方式：

curl http://localhost/health # 返回 'ok' 即前端入口正常 docker exec jonex-gateway curl -s http://localhost:8000/health # 后端不进容器外验证 docker exec jonex-postgres pg_isready -U jonex # 数据库就绪检查

💡 各服务健康检查start_period不同：atomic-rag 为300s（首次需解压模型）、lightrag 60s、Milvus 90s——刚启动时个别容器显示 unhealthy 属正常，耐心等待即可。

第 5 步：存量库执行增量迁移

全新库无需此步（容器首启自动执行postgres/migrations/全量脚本）。已初始化的数据库迭代版本后，须人工显式触发增量 DDL：

make db-migrate-dry # 预览待应用迁移（不执行） make db-migrate # 交互确认后执行

迁移状态记录在public.schema_migrations版本表，已应用文件自动跳过，重复执行安全。

三、可选：启用 GPU 加速，解析速度翻倍

Jonex 的文档解析由atomic-rag服务承担（MinerU VLM、whisper、PaddleX OCR）。宿主机有 NVIDIA GPU 时，叠加 docker-compose.gpu.yml 即可启用 CUDA：

前置条件：已安装 NVIDIA 驱动与nvidia-container-toolkit。

make build-gpu # 构建 GPU 镜像（叠加 gpu.yml） make up-gpu # 启动 GPU 部署 # 验证 GPU 是否生效 docker exec jonex-atomic-rag python -c "import torch; print(torch.cuda.is_available())"

输出True即生效。实测效果：

• MinerU 解析器自动切换 CUDA，复杂文档解析显著提速
• atomic-rag CPU 内存占用从约 4G 降至约 2G
• 显存占用约 6-8G，建议 8GB+ 显存的显卡

四、HTTPS 域名接入：改一行配置即可

Jonex 的 frontend-gateway 镜像内内置两份监听配置，由启动脚本按ACCESS_MODE二选一生成（见 frontend-gateway-mode.sh）：

接入步骤：

1. 将证书放入宿主机目录（文件名固定，只读挂载进容器）：
   • fullchain.crt（含中间证书完整链）
   • private.key
2. 修改deploy/.env：

ACCESS_MODE=https FRONTEND_HTTPS_PORT=443 TLS_CERT_DIR=/opt/jonex/certs # 宿主机证书目录，须为仓库外路径

3. 重新创建容器（关键：environment是容器创建时固化的，restart不生效）：

make up-prod

HTTPS 细节见 server-https.conf：

• 证书缺失时启动脚本会明确报错退出，而非 nginx 晦涩的cannot load certificate
• HSTS 默认不启用（与"随时切回 http"互斥）；确需启用建议从max-age=300起步，稳定后再调大
• 浏览器侧 API 地址为相对路径/api/v1，自动跟随 HTTPS，前端零改动

五、上线前安全加固检查清单

逐项核对 .env.example 后再放流量：

• 密钥类：DB_PASSWORD、NEO4J_PASSWORD、MILVUS_PASSWORD、MINIO_SECRET_KEY均已替换默认值
• JWT_SECRET换为强随机串；JWT_EXPIRE_DAYS按团队要求调整
• GATEWAY_API_KEY、INTERNAL_API_KEY用openssl rand -hex 32重新生成（Gateway 启动守卫会拒绝默认哨兵值）
• LIGHTRAG_API_KEY在.env与.env.rag中一致且非默认值
• ENABLE_TEST_TOKENS=false（生产必须关闭测试 token 免验签）
• DATA_SOURCE_SECRET_KEY已配置（生产必填；python -c "from cryptography.fernet import Fernet;print(Fernet.generate_key().decode())"生成）
• AUTH_CORS_ORIGINS填白名单域名，生产禁用*
• LLM key 只存在于 llm-gateway，下游服务一律走内部 token
• 对外仅开放 80/443；PostgreSQL/Redis/Milvus/Neo4j 均未映射宿主端口
• 前端安全头已内置：CSP（Report-Only）、X-Frame-Options: SAMEORIGIN、X-Content-Type-Options: nosniff、Referrer-Policy（见 app-locations.conf）
• 定期备份：PostgreSQL（pg_dump）、Redis（BGSAVE）、Neo4j（neo4j-admin database dump），命令见 deploy/README.md

六、常见故障排查手册

📌 排查总原则：先make ps-prod看哪个容器不健康，再logs-service看日志，绝大多数问题都能定位到单个服务。

七、写在最后

按本文流程走完，你就获得了一个 GPU 加速、HTTPS 接入、密钥全部收敛的 Jonex 生产环境。后续迭代只需记住三件事：镜像变更用make rebuild-service SERVICE=x，数据库变更先make db-migrate-dry预览，切接入模式改ACCESS_MODE后必须重新make up-prod。祝部署顺利 ✨