Configuration

Source Graph is configured in four layers, each with a different owner and lifetime:

Layer	Where	Changed by	Takes effect
Environment variables	Process environment, for example Fly.io secrets or a container env file	Operator	On restart
Deployment settings	config/deployment.json, embedded at build time	Whoever builds the image	On the next build
Site settings	Database, edited on the Settings page	Administrators	Immediately, with revision checks
Repository policy	Database, set per repository at registration or later	Administrators	On the next synchronization

Secrets — Git tokens, OAuth client secrets, the service token, the credential key and database URLs with passwords — belong only in environment variables or the database, never in the deployment file or the image. For deployment steps see Self-hosting.

Environment variables

Variable	Default	Purpose
SOURCEGRAPH_LISTEN	0.0.0.0:8080	Listen address
SOURCEGRAPH_ORIGIN	http://localhost:8080	Public origin, used for sign-in callbacks and links
SOURCEGRAPH_DATA_ROOT	/data	Data directory; must be absolute
SOURCEGRAPH_DATABASE	sqlite	sqlite, postgres or mongodb
DATABASE_URL	<data root>/sourcegraph.db for SQLite	Database location or connection string
SOURCEGRAPH_MIN_FREE_BYTES	1073741824 (1 GiB)	Free-space floor below which fetching and indexing stop with INSUFFICIENT_STORAGE
SOURCEGRAPH_API_TOKEN	Unset	Optional service token of at least 32 characters; a matching bearer token gets full HTTP API access, except site settings, which require a browser session. The CLI reads the same variable
SOURCEGRAPH_CREDENTIAL_KEY	Generated code-credentials.key in the data root	Base64 of 32 bytes; encrypts stored code-host credentials
SOURCEGRAPH_GIT_TOKEN	Unset	Legacy global GitHub credential, used only while no global github credential has been saved
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET	Unset	Google sign-in
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET	Unset	GitHub sign-in
SOURCEGRAPH_SEED_DEMO	Unset	true registers context4ai/context and context4ai/sourcegraph at startup if they are missing

Changing SOURCEGRAPH_CREDENTIAL_KEY after credentials have been stored makes them unreadable; keep the key with the database backup. With PostgreSQL or MongoDB, several instances can share one database while each keeps its own data directory.

Deployment settings

config/deployment.json is compiled into the binaries and describes what this deployment is, not how it is secured:

Field	Community default	Meaning
code_host	https://github.com	Code host that registrations and credentials target
example_repo	context4ai/context	Repository used in interface examples
public_url	https://context4ai.org/sourcegraph	Public address shown in links and connection snippets
source_repository	https://github.com/context4ai/sourcegraph	Source link shown in the interface
sso	Google issuer and endpoints, empty client ID	Sign-in provider metadata, plus registration_url, the provider console where an operator creates the OAuth client; no secrets

A fork that deploys under its own name or address edits this file and rebuilds; sign-in client IDs and secrets still come from the environment.

Site settings

Administrators edit two sections on the Settings page or through /api/admin/settings. Each save carries the section's current revision; a stale revision is rejected so two administrators cannot silently overwrite each other.

Section	Field	Default	Meaning
repository_defaults	retention_mode	days	Default retention for new registrations: days or count
	retention_days	30	Days of history kept, 1–365
	retention_count	20	Commits kept per branch, 1–4,096
access	public_read	true	Whether anonymous visitors can search and read public repositories
	allow_registration	false	Whether a first-time sign-in creates an account
	registration_notice_zh, registration_notice_en	A built-in notice	Text shown to people who cannot register

Requests to /api/admin/settings must use a browser session; requests carrying an Authorization header are refused. The Storage page separately moves where Git mirrors are kept; see Operations.

Repository policy

Each registration has its own policy, initialized from the repository defaults:

Setting	Range	Default
Monitored branches	1–8	The default branch
Retention	Days 1–365 or commits 1–4,096, not both	Site default
Sync interval (minutes)	1, 3, 5, 10, 30, 60, 180, 360, 720 or 1440	5
Index mode	Whole repository, or registered path groups for a monorepo	Whole repository
Public read	On or off	On
Credential kind (code_provider)	github or git; the registrant's own credential of that kind is tried first, then the global one	github

A repository with public read off is hidden from anonymous visitors only; every signed-in user can still read it. See Registering repositories for how branches and retention decide which commits are searchable.

Plugin limits

Wasm evidence plugins run inside the service under resource guards set by SOURCEGRAPH_PLUGINS_* variables. Invalid values stop startup rather than removing a guard.

Variable suffix	Default	Limits
DISABLED	Unset	1 disables plugins
TIMEOUT	10s	Wall time per run (Go duration)
MEMORY_MIB	256	Memory per instance, at most 4,096
ARTIFACT_BYTES	32 MiB	Plugin module size
METADATA_BYTES	256 KiB	Plugin metadata size
FILE_BYTES	32 MiB	Size of one file the plugin reads
READ_BYTES	128 MiB	Total bytes read per run
READ_CALLS	1,024	File reads per run
OUTPUT_BYTES	2 MiB	Output size
CONCURRENCY	8	Concurrent runs
CACHE_ENTRIES	16	Compiled modules kept
IDLE_INSTANCES	8	Warm instances kept

Built-in limits

Some limits are fixed in code and cannot be configured: request bodies up to 64 KiB, a 30-second request deadline, HTTP server timeouts of 5 seconds for headers, 120 seconds for reading and 125 seconds for writing, and the search, read, list and diff page sizes described in HTTP and MCP. The search engine runs as a local helper on 127.0.0.1:6070 and is never exposed.

Data directory

Path under the data root	Contents	Rebuildable
sourcegraph.db	SQLite database: users, keys, settings, registrations, credentials	No
code-credentials.key	Generated credential key, when SOURCEGRAPH_CREDENTIAL_KEY is unset	No
storage.json	Where Git mirrors are stored on this machine	No
space/	Bare Git mirrors, unless moved on the Storage page	Yes, from the remotes
index/, manifests/	Search index shards and the manifests that describe them	Yes, by indexing again

The container runs as an unprivileged user (uid 10001) and needs write access to the whole data root.

配置

Source Graph 的配置分为四层，每层的负责人和生效周期各不相同：

层级	位置	修改者	生效时机
环境变量	进程环境，例如 Fly.io secrets 或容器 env 文件	运维人员	重启后
部署设置	config/deployment.json，构建时嵌入	构建镜像的人	下次构建后
站点设置	数据库，在 Settings（设置）页面编辑	管理员	立即生效，带版本校验
仓库策略	数据库，按仓库在登记时或之后设置	管理员	下次同步时

机密信息，包括 Git 令牌、OAuth 客户端密钥、服务令牌、凭据加密密钥以及带密码的数据库 URL，只能放在环境变量或数据库中，绝不能放进部署文件或镜像。部署步骤见自部署与数据库选择。

环境变量

变量	默认值	用途
SOURCEGRAPH_LISTEN	0.0.0.0:8080	监听地址
SOURCEGRAPH_ORIGIN	http://localhost:8080	公开源地址，用于登录回调和链接
SOURCEGRAPH_DATA_ROOT	/data	数据目录；必须是绝对路径
SOURCEGRAPH_DATABASE	sqlite	sqlite、postgres 或 mongodb
DATABASE_URL	SQLite 为 <data root>/sourcegraph.db	数据库位置或连接字符串
SOURCEGRAPH_MIN_FREE_BYTES	1073741824（1 GiB）	剩余空间下限，低于该值时拉取和建索引会停止，并返回 INSUFFICIENT_STORAGE
SOURCEGRAPH_API_TOKEN	未设置	可选的服务令牌，至少 32 个字符；匹配的 Bearer 令牌拥有完整的 HTTP API 访问权限，但站点设置除外，站点设置需要浏览器会话。CLI 也读取同一变量
SOURCEGRAPH_CREDENTIAL_KEY	在数据根目录中生成的 code-credentials.key	32 字节的 Base64；用于加密已存储的代码托管平台凭据
SOURCEGRAPH_GIT_TOKEN	未设置	旧版全局 GitHub 凭据，仅在尚未保存全局 github 凭据时使用
GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET	未设置	Google 登录
GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET	未设置	GitHub 登录
SOURCEGRAPH_SEED_DEMO	未设置	设为 true 时，若 context4ai/context 和 context4ai/sourcegraph 尚未登记，会在启动时登记它们

在已存储凭据后修改 SOURCEGRAPH_CREDENTIAL_KEY 会导致这些凭据无法读取；请将该密钥与数据库备份一同保管。使用 PostgreSQL 或 MongoDB 时，多个实例可以共享同一个数据库，同时各自保留自己的数据目录。

部署设置

config/deployment.json 会被编译进二进制文件，描述的是这个部署是什么，而不是如何保障其安全：

字段	社区版默认值	含义
code_host	https://github.com	登记和凭据所针对的代码托管平台
example_repo	context4ai/context	界面示例中使用的仓库
public_url	https://context4ai.org/sourcegraph	在链接和连接代码片段中显示的公开地址
source_repository	https://github.com/context4ai/sourcegraph	界面中显示的源码链接
sso	Google 签发方和端点，客户端 ID 为空	登录提供方元数据，另含 registration_url，即运维人员创建 OAuth 客户端的提供方控制台；不含任何机密

以自己的名称或地址部署的 fork 需要修改此文件并重新构建；登录所用的客户端 ID 和密钥仍来自环境变量。

站点设置

管理员可以在 Settings 页面或通过 /api/admin/settings 编辑两个分区。每次保存都会携带该分区的当前版本；过期的版本会被拒绝，避免两位管理员在不知情的情况下互相覆盖。

分区	字段	默认值	含义
repository_defaults	retention_mode	days	新登记仓库的默认保留策略：days 或 count
	retention_days	30	保留的历史天数，1–365
	retention_count	20	每个分支保留的提交数，1–4,096
access	public_read	true	匿名访客能否搜索和阅读公开仓库
	allow_registration	false	首次登录时是否创建账号
	registration_notice_zh、registration_notice_en	内置提示	向无法注册的人显示的文本

对 /api/admin/settings 的请求必须使用浏览器会话；携带 Authorization 请求头的请求会被拒绝。Storage（存储）页面另外负责迁移 Git 镜像的存放位置；见运维。

仓库策略

每份登记信息都有自己的策略，初始值取自仓库默认值：

设置	范围	默认值
监控分支	1–8 个	默认分支
保留策略	天数 1–365 或提交数 1–4,096，二者不可同时设置	站点默认值
同步间隔（分钟）	1、3、5、10、30、60、180、360、720 或 1440	5
索引模式	整个仓库，或 Monorepo 中已登记的路径组	整个仓库
公开读取	开或关	开
凭据类型（code_provider）	github 或 git；先尝试登记人自己的该类型凭据，再尝试全局凭据	github

关闭公开读取的仓库只对匿名访客隐藏；所有已登录用户仍然可以阅读。分支和保留策略如何决定哪些提交可被搜索，见登记仓库。

插件限制

Wasm 证据插件在服务内部运行，受 SOURCEGRAPH_PLUGINS_* 变量设置的资源防护约束。无效值会导致启动失败，而不是移除对应的防护。

变量后缀	默认值	限制内容
DISABLED	未设置	设为 1 时禁用插件
TIMEOUT	10s	每次运行的墙钟时间（Go duration 格式）
MEMORY_MIB	256	每个实例的内存，最多 4,096
ARTIFACT_BYTES	32 MiB	插件模块大小
METADATA_BYTES	256 KiB	插件元数据大小
FILE_BYTES	32 MiB	插件读取的单个文件大小
READ_BYTES	128 MiB	每次运行读取的总字节数
READ_CALLS	1,024	每次运行的文件读取次数
OUTPUT_BYTES	2 MiB	输出大小
CONCURRENCY	8	并发运行数
CACHE_ENTRIES	16	保留的已编译模块数
IDLE_INSTANCES	8	保留的预热实例数

内置限制

有些限制在代码中写死，无法配置：请求体最大 64 KiB，请求截止时间 30 秒，HTTP 服务器超时分别为请求头 5 秒、读取 120 秒、写入 125 秒，以及HTTP 与 MCP 接口中描述的搜索、读取、列目录和差异分页大小。搜索引擎作为本地辅助进程运行在 127.0.0.1:6070 上，从不对外暴露。

数据目录

数据根目录下的路径	内容	可否重建
sourcegraph.db	SQLite 数据库：用户、Key、设置、登记信息、凭据	否
code-credentials.key	未设置 SOURCEGRAPH_CREDENTIAL_KEY 时生成的凭据加密密钥	否
storage.json	本机上 Git 镜像的存放位置	否
space/	裸 Git 镜像，除非已在 Storage 页面迁移	可以，从远端重新拉取
index/、manifests/	搜索索引分片及描述它们的清单	可以，重新建索引即可

容器以非特权用户（uid 10001）运行，需要对整个数据根目录拥有写权限。