部署前先了解 Jan 的 Docker 形态
Jan 是一类面向个人和团队的本地AI助手，常见用途包括本机对话、知识整理、调用本地模型、接入兼容 OpenAI 风格的接口等。使用 Docker 部署的好处是环境隔离、迁移方便、升级回退更可控，不必在宿主机上手动安装大量依赖。对想在工作站、迷你主机、实验服务器上长期运行 AI 工具的用户来说，Docker 方式更适合做成稳定服务。
需要注意的是，Jan 的镜像名称、容器内数据路径和默认端口可能会随版本调整。正式操作前，应以 Jan 官方文档、官方 GitHub 或镜像仓库页面为准，确认镜像来源、标签版本、端口说明和挂载目录。下文使用通用写法演示部署思路，示例镜像可写作 ghcr.io/janhq/jan:latest，实际环境中请替换为官方当前推荐的镜像地址。
准备环境与目录规划
部署前先确认宿主机已安装 Docker，并能正常执行 docker version。如果计划长期使用，建议同时安装 Docker Compose，便于后续维护。硬件方面，纯 CPU 运行可以启动服务，但模型响应速度受处理器和内存影响较大；如果要运行较大的本地模型，应提前评估内存、显存、磁盘空间和散热能力。磁盘建议预留几十 GB 以上空间，模型文件会持续增长。
目录规划建议单独放在一个固定路径，例如 /opt/jan。其中 /opt/jan/data 用于保存配置、会话、索引等数据，/opt/jan/models 用于存放模型文件，/opt/jan/logs 用于保存日志。这样做的好处是容器删除或重建后，核心数据仍保留在宿主机，升级、迁移、备份都更简单。创建目录可执行：mkdir -p /opt/jan/data /opt/jan/models /opt/jan/logs。
方式一：使用 docker run 快速启动
首次部署可以先用 docker run 验证镜像是否可用。先拉取镜像：docker pull ghcr.io/janhq/jan:latest。如果希望版本稳定，不建议长期使用 latest，可以改为官方发布的明确版本号，例如 ghcr.io/janhq/jan:0.x.x。明确版本有利于排查问题，也便于在升级失败时回到旧版本。
启动示例：docker run -d --name jan --restart unless-stopped -p 1337:1337 -v /opt/jan/data:/data -v /opt/jan/models:/models -v /opt/jan/logs:/logs ghcr.io/janhq/jan:latest。其中 -d 表示后台运行，--restart unless-stopped 表示异常退出后自动重启，-p 1337:1337 表示把宿主机 1337 端口映射到容器内 1337 端口，-v 则是数据目录挂载。
如果官方文档注明容器内端口不是 1337，例如 3000、8080 或其他端口，应把命令中的容器端口同步改掉。端口格式是 宿主机端口:容器端口，例如 -p 18080:8080 表示用户访问宿主机 18080，实际转到容器内 8080。宿主机端口可以自定义，但不要与已有服务冲突。
方式二：使用 Compose 一键维护
长期运行更推荐 Compose。可在 /opt/jan/docker-compose.yml 中写入服务配置，核心内容包括镜像、容器名、端口、数据卷和重启策略。示例结构为：服务名 jan，镜像 ghcr.io/janhq/jan:latest，端口 1337:1337，挂载 /opt/jan/data:/data、/opt/jan/models:/models、/opt/jan/logs:/logs，重启策略 unless-stopped。保存后在目录内执行 docker compose up -d 即可启动。
Compose 的优势在于配置可读、可复制、可纳入运维记录。修改端口、升级镜像、添加环境变量时，不必重新拼接很长的命令。查看运行状态可用 docker compose ps，查看日志可用 docker compose logs -f，停止服务可用 docker compose down。如果只想重启，不删除网络和容器，可执行 docker compose restart。
端口映射与访问验证
容器启动后，先用 docker ps 查看是否处于 Up 状态，再用浏览器或接口工具访问 https://宿主机IP:1337。如果 Jan 提供的是接口服务，也可以访问兼容接口路径进行验证，例如查看健康检查地址或模型列表地址，具体路径以官方说明为准。若本机部署本机访问，可使用 https://127.0.0.1:1337。
端口无法访问时，优先检查四点：第一，容器是否正常运行；第二，映射格式是否写反；第三，宿主机端口是否被其他程序占用；第四，服务器安全规则是否允许访问该端口。可用 docker logs jan 查看启动报错，用 docker inspect jan 查看端口绑定结果。若只供本机使用，可把端口绑定到本地地址，例如 -p 127.0.0.1:1337:1337，减少外部访问面。
数据目录与权限配置
AI 工具的数据目录非常关键，里面可能包含模型、对话记录、配置文件、插件缓存和索引文件。部署时一定要把这些路径挂载到宿主机，避免容器重建后数据丢失。若官方镜像说明数据目录为 /root/.jan 或 /home/jan/.jan，应按真实路径挂载，例如 -v /opt/jan/data:/root/.jan。如果镜像支持 JAN_DATA_DIR、MODEL_DIR 等环境变量，也可以用环境变量指定数据位置。
权限问题是 Docker 部署中最常见的故障之一。表现包括无法下载模型、无法写入配置、启动后反复报错。处理方法是确认容器内运行用户的 UID/GID，再调整宿主机目录权限。简单测试环境可使用 chmod 放宽目录权限，但生产环境不建议长期使用过宽权限。更稳妥的方式是用 chown 把目录归属调整为容器运行用户，或者在 Compose 中指定 user 参数。
镜像版本、升级与回退
升级前先备份 /opt/jan/data 和 /opt/jan/models。模型目录通常较大，可以只备份配置和索引数据，但重要模型建议保留原始文件来源或校验信息。升级流程通常是：停止容器，拉取新镜像，重新启动。命令可按顺序执行 docker compose down、docker compose pull、docker compose up -d。
如果升级后出现页面异常、接口不兼容或模型加载失败，应先查看日志，不要急着删除数据目录。回退时把 Compose 中的镜像标签改回旧版本，再执行 docker compose up -d。为了降低风险，建议不要在重要工作时段升级，也不要把主力环境直接绑定到不确定的测试版本。对稳定性要求高的用户，应固定版本号，并记录每次变更的时间、版本和配置。
常见问题排查
容器启动后马上退出，多数是镜像架构不匹配、缺少必要参数、目录无权限或端口冲突。可通过 docker logs jan --tail=200 查看最后的错误信息。拉取镜像失败时，先确认镜像地址和标签是否正确，再检查 Docker 是否能访问对应镜像仓库。模型下载失败时，要区分是 Jan 应用问题、模型源不可用，还是宿主机磁盘空间不足。
访问很慢不一定是部署失败。本地模型推理对硬件要求较高，首次加载模型也需要时间。可以先选择体积较小的模型验证流程，再逐步切换到更大的模型。若机器内存不足，可能出现服务卡顿或容器被系统终止。此时应减少并发、降低模型规模，或为容器设置合理资源限制，避免影响同机其他服务。
安全边界与实用建议
Jan 作为本地AI助手，通常会接触到工作文本、知识库和个人资料，因此不建议把管理界面直接暴露到公网。若必须远程访问，应放在受控网络环境中，并配置访问认证、反向袋里访问规则和日志审计。不要把包含密钥、内部资料、客户信息的目录随意挂载进容器，也不要在不明来源镜像中运行敏感任务。
实用建议是：第一，只使用官方或可信来源镜像；第二，固定镜像版本，避免不可预期变更；第三，数据目录独立挂载并定期备份；第四，端口只开放给必要范围；第五，升级前先看发布说明。按这个思路部署，Jan 的 Docker 环境既能保持一键启动的便利，也能在模型增长、配置变化和版本更新时保持可维护性。
