部署前先明确：群晖上装的是什么
Perplexity AI 本身是在线 AI 搜索问答服务，通常不能像普通开源软件一样完整私有化安装到家用 NAS。群晖 Docker 部署场景里，常见做法有两类：一是部署第三方开源的“类 Perplexity”检索问答前端，例如支持联网检索、引用来源、接入大模型 API 的项目；二是部署一个轻量 Web 服务，通过 Perplexity API 或其他模型接口实现问答能力。操作前要先看清项目说明、镜像来源、许可证和环境变量要求，避免把“官方服务”误认为“可离线完整部署”。
这类部署适合三种用户：已经有群晖 NAS，希望在本地统一管理 AI 工具；需要给团队或家庭成员提供固定入口；希望保留会话、配置、索引等数据在自己的设备中。它不适合追求完全离线推理的场景，因为多数检索问答工具仍需要外部模型接口和搜索接口，网络连通性、API 配额、密钥安全都会影响体验。
准备工作：系统、套件与账号信息
建议群晖系统使用 DSM 7.x，并在“套件中心”安装 Container Manager；旧版系统可能显示为 Docker，界面略有差异，但核心概念相同。NAS 至少预留 2GB 以上可用内存，若同时运行数据库、向量检索或本地模型，建议提高到 4GB 以上。存储空间方面，为配置文件、日志和缓存单独建立共享文件夹，例如 docker/perplexity-ai，后续升级和迁移会更清楚。
还需要提前准备模型服务的 API Key。若项目支持 Perplexity API，就准备对应密钥；若支持 OpenAI、Anthropic、Ollama 或其他兼容接口，也要确认 base URL、模型名称、鉴权方式。密钥不要写在公开文档、截图或多人可见的备注里，更不要提交到公开代码仓库。群晖上建议通过环境变量填写，必要时限制容器管理权限，只让可信账号维护。
镜像选择与目录规划
打开项目主页或镜像仓库时，重点看四项信息：最近更新时间、启动命令、必填环境变量、是否需要附加服务。有些项目一个镜像即可运行，有些需要同时启动 Web、API、Redis、数据库或搜索服务。新手优先选择官方文档提供 docker compose 示例的项目，因为依赖关系、端口和卷映射会更完整。
目录可以按功能拆分：/docker/perplexity-ai/config 存放配置，/docker/perplexity-ai/data 存放应用数据，/docker/perplexity-ai/logs 存放导出的日志。如果项目需要数据库，则再建 /docker/perplexity-ai/db。这样做的好处是容器删除后数据仍在，升级镜像时只需重建容器，不必重新配置。不要把核心数据只放在容器内部，否则容器重置后会丢失。
方式一：使用 Container Manager 图形界面部署
进入 Container Manager，先在“映像”页面搜索项目镜像，优先选择项目文档指定的镜像名和标签。标签不要盲目使用 latest，生产使用建议固定版本号，测试确认无误后再升级。下载完成后点击“运行”，容器名称可设为 perplexity-ai-web，便于后续识别。
端口设置是新手最容易出错的地方。容器内部端口以项目文档为准，例如应用监听 3000，则本地端口可以映射为 3008:3000，表示用 NAS 的 3008 端口访问容器的 3000 端口。如果提示端口被占用，就换一个未使用的本地端口。卷映射时，将群晖的 /docker/perplexity-ai/data 映射到容器要求的数据路径，配置目录也按文档填写，不要随意猜路径。
环境变量页面需要填写 API Key、模型名、接口地址、站点地址等参数。常见变量包括 PERPLEXITY_API_KEY、OPENAI_API_KEY、MODEL_NAME、BASE_URL、APP_URL、TZ 等，实际名称以项目文档为准。TZ 可填 Asia/Shanghai，便于日志时间对齐。确认后启动容器，等待几十秒，再访问 https://群晖IP:本地端口。
方式二：使用项目编排文件部署
如果项目提供 compose 配置，推荐使用“项目”功能部署。新建项目，将配置内容粘贴进去，再把环境变量集中写好。编排方式更适合多容器应用，例如前端、后端、缓存和数据库需要一起启动时，依赖关系更清楚，后续重建也更稳定。
使用编排文件时要检查三处：第一，volumes 左侧路径必须改成群晖真实路径；第二，ports 左侧端口不要与已有服务冲突；第三，environment 中的密钥和模型地址不要留空。保存后启动项目，观察所有容器是否都处于运行状态。如果某个依赖容器反复重启，先不要急着改前端配置，应从最底层的数据库、缓存或检索服务日志开始看。
首次访问与基础验证
容器状态显示“运行中”不代表应用可用。首次打开页面后，先测试三件事：能否进入首页，能否提交一个简单问题，回答中是否带有来源或检索结果。如果页面能打开但无法回答，多半是模型接口配置、密钥、配额或后端连通问题；如果页面打不开，则优先排查端口映射、防火墙、容器监听地址和应用启动日志。
建议建立一个最小验证问题，例如“请概括今天的技术新闻检索结果”，看它是否真的触发检索。部分项目默认只调用模型，不会自动联网检索，需要在设置里启用 search provider，或配置搜索 API。不要把模型的“看似准确回答”等同于真实检索结果，若业务场景对来源要求高，应要求输出引用链接并人工抽查。
日志排错：先看启动，再看请求
Container Manager 中进入容器详情，打开“日志”标签即可看到标准输出。启动失败常见关键词包括 missing environment variable、invalid api key、connection refused、permission denied、port already in use、cannot find module 等。看到 missing environment variable，说明必填参数没写或名称写错；看到 invalid api key，优先检查密钥是否复制完整、是否多了空格、是否选错服务商；看到 permission denied，多数是映射目录权限不足。
如果习惯命令行，可通过 SSH 登录群晖后执行 docker ps 查看容器名，再用 docker logs 容器名 --tail 200 查看最近日志，用 docker logs -f 容器名 实时跟踪。容器反复重启时，先用 docker inspect 容器名 查看退出码和重启策略。退出码 1 通常是应用配置错误，137 往往与内存不足有关，健康检查失败则要看应用实际监听端口和健康接口路径是否匹配。
请求阶段的错误要结合时间点判断。提交问题后立刻报错，日志出现 401 或 403，多为鉴权失败；出现 404，可能是接口地址或模型名称不对；出现 429，说明请求过于频繁或额度受限；出现 timeout，可能是外部接口响应慢、DNS 异常或服务端不可达。排查时一次只改一个变量，修改后重启容器并记录结果，避免多处同时调整导致无法回溯。
常见问题与处理方法
页面空白：先清理页面缓存并换一个访问入口测试，再看前端日志是否构建失败或静态资源路径错误。若部署在反向袋里后面，要确认 APP_URL、PUBLIC_URL 或类似变量与实际访问地址一致。
容器启动后马上停止：查看日志第一屏，通常能看到缺少配置、数据库连不上或目录不可写。确认卷映射路径存在，并在群晖“控制面板”的共享文件夹权限中给容器运行用户足够读写权限。
能访问页面但回答失败：检查 API Key、模型名称、接口地址和项目支持的协议。很多工具支持“兼容 OpenAI 格式”的接口，但并不代表所有模型名都能直接使用。必要时先用项目自带的测试接口或最简单的 curl 请求验证。
升级后异常：不要直接覆盖重要环境。先备份 data、config 和 compose 配置，再拉取新镜像。若新版不兼容，可把镜像标签改回旧版本并重建容器。升级前阅读 release notes，特别关注环境变量改名、数据库迁移和端口变化。
安全边界与维护建议
不要把服务直接暴露到公网，尤其是未开启登录鉴权的 AI 问答页面。若确需外部访问，应使用群晖自带的安全访问方案、强密码、双重验证和访问控制，并定期查看登录记录。API Key 属于敏感凭据，一旦怀疑泄露，应立即在服务商后台删除旧密钥并生成新密钥。
日志中可能包含用户提问、接口返回和错误详情，导出给他人排查前要先脱敏。团队使用时应明确哪些内容可以提交给 AI，避免上传合同、客户资料、内部文档等敏感信息。对于检索结果，也要保留人工复核流程，尤其是用于工作决策、技术配置和公开发布时，不能只依赖模型输出。
稳定运行后，建议每月做三件事：检查镜像是否有安全更新，备份配置与数据目录，清理过大的日志和缓存。群晖资源有限时，不要同时堆太多 AI 容器；发现 NAS 长期高负载，应限制容器内存、关闭不必要的后台任务，或将本地模型推理迁移到更合适的计算设备。这样才能让 Perplexity AI 类工具既好用，又不影响 NAS 的核心存储和同步任务。
