部署前先弄清：Cody与Sourcegraph的关系
Sourcegraph Cody常被理解为“AI代码搜索工具”，更准确地说，它是围绕代码库理解、检索、问答和补全展开的智能开发助手。Cody通常通过编辑器插件使用，而其代码上下文能力依赖Sourcegraph对代码库的索引、搜索和权限管理。对团队来说，使用Docker先部署一个Sourcegraph实例，再接入Cody，是较容易落地的方案：不需要在主机上安装大量组件，后续迁移、升级和回滚也更可控。
这类部署适合中小团队试用、内网代码库检索、AI辅助研发验证、私有项目上下文管理等场景。需要注意的是，Docker单容器部署更偏向快速体验和轻量生产，若代码库规模很大、并发用户较多，应进一步规划独立数据库、对象存储、监控告警和高可用架构，避免把试用方案直接当作长期核心平台。
环境准备与安全边界
服务器建议至少准备2核CPU、4GB内存和40GB可用磁盘空间；如果代码库较多，建议从8GB内存起步，并为数据目录单独挂载容量更大的磁盘。系统可选择常见Linux发行版，提前安装Docker Engine，并确认当前用户有执行Docker命令的权限。
安全边界要提前设定：不要把管理端口直接暴露到不可信网络；不要把访问令牌、模型服务密钥写进公开脚本；不要把宿主机根目录直接挂载进容器；不要在未备份数据目录的情况下执行清理命令。若用于团队协作，应启用账号体系、仓库权限同步和访问审计，避免代码内容被无关人员检索到。
拉取Sourcegraph镜像
官方常用镜像为sourcegraph/server。首次部署建议固定版本号，便于问题排查和后续回滚。例如可以先查看官方发布说明，选择一个稳定版本，再执行：docker pull sourcegraph/server:版本号。如果只是本地测试，也可以使用latest，但不建议生产环境长期依赖该标签，因为每次拉取可能对应不同版本。
镜像拉取较慢时，优先检查服务器网络、DNS解析和Docker配置。不要随意使用来源不明的第三方镜像，尤其是带有“优化版”“特别版”描述的镜像，可能存在后门、版本滞后或配置被篡改等风险。拉取完成后，可用docker images确认镜像名称、标签和大小是否正常。
规划端口映射
Sourcegraph容器默认对外提供Web访问端口，常见映射方式是将宿主机的7080端口映射到容器内部的7080端口。启动后，用户可通过https://服务器地址:7080访问控制台。若服务器上已有服务占用7080，可改为其他宿主机端口，例如-p 18080:7080，此时访问地址变为https://服务器地址:18080。
端口设计要兼顾安全和运维习惯。测试阶段可只允许运维人员IP访问；正式使用时建议放在统一入口后面，通过反向袋里处理访问域名、证书和日志。若启用外部访问，应检查防火墙策略，只开放必要端口。不要为了省事开放大范围端口，也不要把Docker守护进程控制端口暴露到公网。
配置数据目录挂载
Sourcegraph的仓库索引、配置、用户数据和运行状态都应持久化保存。推荐在宿主机创建独立目录，例如：/data/sourcegraph/config、/data/sourcegraph/data。随后启动容器时使用-v参数挂载到容器内部对应位置，避免容器删除后数据随之丢失。
一个常见启动命令可以写成：docker run -d --name sourcegraph -p 7080:7080 -v /data/sourcegraph/config:/etc/sourcegraph -v /data/sourcegraph/data:/var/opt/sourcegraph sourcegraph/server:版本号。其中--name用于固定容器名称，便于后续执行日志查看、停止、重启和升级操作。若宿主机启用了更严格的安全策略，还要关注目录属主和读写权限，确保容器进程可以正常写入。
首次启动与初始化
容器启动后，可执行docker ps确认运行状态，再用docker logs -f sourcegraph观察初始化日志。首次启动可能需要数分钟，期间会准备内部服务、数据库文件和搜索索引组件。浏览器打开访问地址后，按照页面提示创建管理员账号，进入管理后台。
完成初始化后，建议先配置站点URL、邮件通知、用户登录方式和仓库来源。接入代码仓库时，应使用最小权限的访问凭据，只授予读取所需项目的权限。导入仓库后，Sourcegraph会逐步建立索引，初期搜索结果可能不完整，等待后台任务完成即可。Cody侧可在编辑器插件中填写Sourcegraph实例地址，并完成登录授权，让插件获取项目上下文。
Cody相关配置思路
Cody的核心价值在于让开发者围绕当前代码库提问、解释函数、生成测试、定位调用链和辅助重构。团队部署时应明确两类配置：一类是Sourcegraph负责的代码库连接、索引和权限；另一类是Cody使用的模型服务、访问策略和用户范围。若企业已有统一模型服务，可在管理后台按官方文档填写接口地址和密钥；若只是体验，可先使用支持的托管能力完成验证。
配置模型服务时，不要在浏览器截图、工单或群聊中泄露密钥。建议为Cody单独创建访问凭据，并设置额度、可访问模型和失效时间。对于包含敏感业务逻辑的仓库，应先确认数据流向和合规要求，再决定是否允许AI问答读取相关上下文。
常见问题与排查办法
访问页面失败，先检查容器是否运行：docker ps -a；若容器反复重启，查看日志中是否有端口占用、磁盘不足、权限拒绝等提示。端口无法访问时，确认启动命令的-p映射是否正确，服务器防火墙是否放行，云主机安全策略是否允许该端口。
仓库导入后搜索不到内容，通常是索引任务尚未完成、仓库凭据权限不足或仓库地址配置错误。可以进入后台查看仓库同步状态和任务队列。Cody无法连接时，检查Sourcegraph地址是否能从本机浏览器访问，插件是否完成登录，账号是否有对应仓库权限。AI回答质量不稳定时，应优先确认代码索引是否完整、当前工程是否打开正确，以及提问是否包含足够上下文。
升级、回滚与备份
升级前必须备份数据目录，尤其是/data/sourcegraph/config和/data/sourcegraph/data。推荐步骤是：停止容器，打包数据目录，拉取新版本镜像，使用相同挂载参数启动新容器。不要在不阅读版本说明的情况下跨多个大版本升级，因为配置项、索引结构或依赖组件可能发生变化。
回滚的关键是“镜像版本可找回、数据备份可恢复”。如果升级后出现异常，可停止新容器，重新使用旧版本镜像，并恢复升级前备份的数据目录。需要注意，某些版本升级后可能会执行数据迁移，直接用迁移后的数据启动旧版本未必成功，因此升级前的离线备份非常重要。
运维建议与最佳实践
长期运行时，建议配置容器自动重启策略，例如增加--restart unless-stopped。同时定期检查磁盘空间、容器日志大小、索引任务状态和访问异常。代码库数量增长后，搜索索引和缓存会持续占用空间，应提前规划容量，并建立清理和扩容流程。
团队推广Cody时，不宜只把它当成“代码生成器”。更稳妥的用法是让它做代码解释、接口梳理、单元测试草稿、变更影响分析和旧项目熟悉辅助。所有AI生成的代码都应经过人工审查、测试验证和安全扫描。部署只是第一步，真正发挥价值还需要规范仓库权限、完善索引质量、沉淀提示词范式，并让开发者理解它的能力边界。
