企业官网建设流程全解析

• 后端
• 数据存储

Perkeep（前身 Camlistore）是一个面向个人的长期存储系统，其大量运行时行为——从客户端认证、GPG 密钥选择、目录定位，到索引后端切换、网络限速与调试开关——都通过一组CAMLI_*（以及少量PERKEEP_*、DEV_*、AWS_*、CAMPUT_*、PK_*）环境变量来控制。本文以 doc/environment-vars.md 为骨架，结合仓库源码与 devcam 的实际注入逻辑，逐条讲解每个变量的用途、取值约定、优先级关系与底层实现，帮助你理解 Perkeep 各组件（客户端、服务端、devcam、索引器、发布器）的配置体系，并能直接应用于自己的部署与开发调试。

一、环境变量的通用解析规则

Perkeep 对布尔型与整数型环境变量有统一的解析约定，理解这一点可以避免大量踩坑。

布尔值的隐式转换

所有布尔环境变量均使用 Go 标准库的strconv.ParseBool解析，它只接受以下值（大小写敏感地接受大小写变体）：

• 真值：1、t、T、TRUE、true、True
• 假值：0、f、F、FALSE、false、False

任何其他值都会被视为隐式false（即"非 1/true 即关闭"）。这意味着你不需要显式设置=false来关闭某功能，留空或不设置即可；而设置CAMLI_DEBUG=yes之类是无效的，必须用CAMLI_DEBUG=1或CAMLI_DEBUG=true。

仓库中的大量读取都遵循这一约定，例如 pkg/env/env.go 中：

isDev = os.Getenv("CAMLI_DEV_CAMLI_ROOT") != "" isDebug, _ = strconv.ParseBool(os.Getenv("CAMLI_DEBUG")) isDebugUploads, _ = strconv.ParseBool(os.Getenv("CAMLI_DEBUG_UPLOADS"))

注意CAMLI_DEV_CAMLI_ROOT是一个字符串变量，其判空方式与布尔变量不同。

整数值的限制

整数值使用strconv.Atoi解析，这意味着只接受十进制数，十六进制（0x1F）、八进制（017）等格式都会解析失败并回退为零。典型应用见 pkg/webserver/webserver.go 中读取DEV_THROTTLE_KBPS与DEV_THROTTLE_LATENCY_MS的方式：

kBps, _ := strconv.Atoi(os.Getenv("DEV_THROTTLE_KBPS")) ms, _ := strconv.Atoi(os.Getenv("DEV_THROTTLE_LATENCY_MS"))

二、通用（General）环境变量：路径、认证与客户端行为

这一节变量影响 Perkeep 客户端的连接、目录定位、密钥选择与上传行为，是日常部署中最常接触的一批。

AWS 凭据（S3 测试）

• AWS_ACCESS_KEY_ID（string）
• AWS_ACCESS_KEY_SECRET（string）

这对变量用于 S3 相关的测试场景。若未设置，依赖真实 S3 的测试会被跳过；一旦设置，查询会真实发往 Amazon S3 服务。生产环境的 S3 存储配置应放在 blobserver 的配置文件中而非环境变量。

应用可执行文件目录

CAMLI_APP_BINDIR（string）：Perkeep 启动服务端应用（如 publisher、scanningcabinet 等）时首先在此目录查找可执行文件，找不到再回退到PATH。devcam server 会将其显式设为bin，见 dev/devcam/server.go。

认证与服务器选择

CAMLI_AUTH（string）：客户端认证方式的兜底配置。当配置文件（client-config.json）缺少auth条目时使用；尤其当客户端通过命令行-server指定 Perkeep 实例时，此环境变量优先于配置文件中的 auth。具体读取逻辑见 pkg/client/config.go 的SetupAuth——它仅在 Android 或 dev 模式（env.IsDev()）或配置文件被禁用时优先从环境变量取 auth，其余场景以配置文件为准。devcam 会注入CAMLI_AUTH=userpass:camlistore:pass3179（服务端则覆盖为devauth:pass3179）。

CAMLI_DEFAULT_SERVER（string）：默认使用的服务器别名，取值是 client-config.json 中servers对象的别名键。设置后其优先级高于配置文件中的"default": true标记。见 pkg/client/config.go 的defaultServer实现：

wantAlias := os.Getenv("CAMLI_DEFAULT_SERVER") for alias, serverConf := range config.Servers { if (wantAlias != "" && wantAlias == alias) || (wantAlias == "" && serverConf.IsDefault) { return cleanServer(serverConf.Server) } }

目录定位（缓存、配置、变量目录）

• PERKEEP_CACHE_DIR或CAMLI_CACHE_DIR（string）：覆盖操作系统默认缓存目录。PERKEEP_前缀是新命名，CAMLI_前缀保留兼容。实现见 internal/osutil/paths.go：先检查PERKEEP_CACHE_DIR，再检查CAMLI_CACHE_DIR，之后按平台回退（macOS 的~/Library/Caches/Camlistore、Windows 的%TEMP%/%TMP%、Linux 的$XDG_CACHE_HOME或~/.cache/perkeep）。
• CAMLI_CONFIG_DIR（string）：覆盖操作系统特定配置目录。对应 internal/osutil/paths.go 的PerkeepConfigDir，它进一步决定了客户端与服务端配置文件的查找位置（server-config.json与client-config.json）。
• CAMLI_VAR_DIR（string）：覆盖应用数据存储目录（blob 根目录等），文档标注"generally unused"，见 internal/osutil/paths.go 的camliVarDirOf。

数据库名

CAMLI_DBNAME（string）：索引后端的数据库名/DSN。devcam server 会为不同索引后端生成不同值，例如 sqlite 时设为root/sqliteindex.db、kv 时设为root/kvindex.db、leveldb 时设为root/leveldbindex.db，见 dev/devcam/server.go。

开发根目录与 Closure 库

• CAMLI_DEV_CAMLI_ROOT（string）：dev 模式下 Perkeep 源码根目录。它被 pkg/server/ui.go 用来定位静态资源（js、css、html），同时被 pkg/index 与 pkg/server 用作信号，在 devcam 环境下输出更友好的错误信息。pkg/env中IsDev()正是以该变量是否非空来判断（pkg/env/env.go）。
• CAMLI_DEV_CLOSURE_DIR（string）：覆盖服务端 Closure 库的提供路径。devcam 的-fullclosure会设置它为clients/web/embed/closure/lib/closure（dev/devcam/server.go），服务端在 pkg/server/ui.go 读取并直接使用该目录提供 closure handler。

导入器开关

CAMLI_DISABLE_IMPORTERS（bool）：为 true 时禁用导入器（至少是自动后台导入，例如启动时的导入）。源码 pkg/importer/importer.go：

var disableImporters, _ = strconv.ParseBool(os.Getenv("CAMLI_DISABLE_IMPORTERS"))

主要用于调试。

构建强制开关

CAMLI_FORCE_OSARCH（bool）：供make.go使用，强制构建不受支持的 OS/ARCH 组合。典型场景见 make.go：当检测到 32 位 Mac 构建时直接报错并提示"要强行构建请设置CAMLI_FORCE_OSARCH=1"。

Hello 示例应用

CAMLI_HELLO_ENABLED（bool）：是否额外启动 hello world 示例应用。仅 devcam server 使用，devcam 的-hello标志会映射为它（dev/devcam/server.go）。

客户端忽略文件

CAMLI_IGNORED_FILES（string）：覆盖客户端配置ignoredFiles选项，是逗号分隔的、上传时由 pkg/client 忽略的文件列表。实现见 pkg/client/config.go：设置时按逗号切分并立即生效，否则回退到配置文件。忽略规则支持 shell 通配模式、绝对路径前缀与路径组件三种匹配方式。

配置包含搜索路径

CAMLI_INCLUDE_PATH（string）：配置文件include引用的文件搜索路径。它被 internal/osutil/paths.go 的NewJSONConfigParser使用：搜索顺序是当前目录 → Perkeep 配置目录 → 此环境变量路径（作为最后兜底）。路径格式遵循 OS 约定：类 Unix 用冒号分隔（/path/1:/path/two），Windows 用分号分隔（C:\path\one;D:\path\2）。

GPG 身份与密钥环

• CAMLI_KEYID（string）：可选 GPG 身份标识，优先于配置文件。devcam 命令、config/dev-server-config.json、config/dev-client-dir/client-config.json 都把它用作签名 GPG 公钥的 ID。客户端侧 pkg/client/config.go 先读CAMLI_KEYID，为空才回退到配置文件identity字段。
• CAMLI_SECRET_RING（string）：GPG 私钥环路径，否则由服务端配置的identitySecretRing、客户端配置的secretRing决定。解析顺序为：命令行-secret-keyring标志 >CAMLI_SECRET_RING> 配置文件 > 系统默认位置，见 internal/osutil/paths.go。

索引校验与索引后端开关（devcam）

• CAMLI_KV_VERIFY（bool）：启用 cznic/kv 的全部VerifyDb*选项，用于追踪数据损坏。devcam 默认注入true（dev/devcam/env.go）。
• CAMLI_KVINDEX_ENABLED、CAMLI_LEVELDB_ENABLED、CAMLI_MEMINDEX_ENABLED（bool）：分别启用 cznic/kv、syndtr/goleveldb、纯内存索引器。三者仅 devcam server 使用，一一对应 devcam 的-kvfile、默认/-memory开关（dev/devcam/server.go）。
• CAMLI_MONGO_WIPE（bool）：启动时清空基于 mongo 的索引。

上传去重搜索

CAMLI_NO_FILE_DUP_SEARCH（bool）：为 true 时，pk put上传文件时跳过"上传前先搜索是否已存在"的步骤。适合批量灌入新数据、明确不需要去重检查的场景，可显著减少查询开销。

启动期性能剖析

CAMLI_PPROF_START（string）：作为文件名前缀，在服务端启动期间写出<base>.cpu与<base>.mem两个 profile 文件，主要用于剖析索引语料库（corpus）扫描。实现见 pkg/serverinit/serverinit.go：

if v := os.Getenv("CAMLI_PPROF_START"); v != "" { cpuf := mustCreate(v + ".cpu") defer cpuf.Close() memf := mustCreate(v + ".mem") defer memf.Close() rpprof.StartCPUProfile(cpuf) defer rpprof.StopCPUProfile() defer rpprof.WriteHeapProfile(memf) }

应用开关（devcam）

• CAMLI_PUBLISH_ENABLED（bool）：是否同时启动 publisher 应用。对应 devcam-publish（默认 true，dev/devcam/server.go）。
• CAMLI_SCANCAB_ENABLED（bool）：是否同时启动扫描柜（scanning cabinet）应用，对应 devcam-scancab。
• CAMLI_HELLO_ENABLED（bool）：见上文。

禁用客户端配置文件

CAMLI_DISABLE_CLIENT_CONFIG_FILE（bool）：设置后 pkg/client 将完全不用磁盘上的配置文件。注意这会连带引发parseConfigpanic 约束（pkg/client/config.go），因此通常只在特殊隔离场景使用，配置必须全部通过其他途径（如环境变量）提供。

FUSE 文件系统统计

CAMLI_TRACK_FS_STATS（bool）：为 fuse 文件系统启用操作计数，用于观察挂载点上的读写行为。

信任证书

CAMLI_TRUSTED_CERT（string）：覆盖客户端配置trustedCerts，是逗号分隔的受信任证书指纹路径列表。见 pkg/client/config.go：设置后直接切分使用，忽略配置文件。

Android 客户端输出

CAMPUT_ANDROID_OUTPUT（bool）：启用 pkg/client 的状态消息输出到 stdout，供 Android 客户端使用（Android 上无法直接访问终端，需打印到日志/输出通道）。

禁用 djpeg 降采样

CAMLI_DISABLE_DJPEG（bool）：禁用djpeg(1)将 JPEG 按 2、4、8 倍率降采样的能力。仅在 PATH 中能找到 djpeg 时才有实际效果，见 internal/images/fastjpeg 相关实现。

缩略图缓存

PK_DISABLE_THUMB_CACHE（bool）：为 true 时不做缩略图缓存，且 URL 携带 cache-buster 组件，强制浏览器频繁重新加载。适合开发调试 pkg/server/thumbcache.go 相关功能。

强制重新索引

CAMLI_REDO_INDEX_ON_RECEIVE（bool）：为 true 时，索引器对每一个收到的 blob 都强制重新索引，无论之前是否已索引过。仅适用于增量开发索引代码、对内容子集做回溯索引而无需全局重建的场景，生产环境慎用。

S3 故障注入

CAMLI_S3_FAIL_PERCENT（int）：0-100 的整数，表示 S3 handler 接收 blob 时人为失败的百分比，用于故障注入测试。

三、开发（Development）环境变量：调试、限速与测试

• CAMLI_DEBUG（bool）：perkeepd 与pk put用它启用额外命令行选项，pkg/schema 用它启用额外日志。被 pkg/env/env.go 读取为全局调试开关。
• CAMLI_HTTP_DEBUG（bool）：在 pkg/webserver 启用按请求日志。见 pkg/webserver/webserver.go：verbose, _ := strconv.ParseBool(os.Getenv("CAMLI_HTTP_DEBUG"))。
• CAMLI_DEBUG_CONFIG（bool）：让 pkg/serverconfig 在加载时转储由高层配置推导出的低层配置，用于排查配置展开问题。
• CAMLI_DEBUG_X（string）：包含魔术子串以启用代码内调试。已知用法见 make.go：strings.Contains(os.Getenv("CAMLI_DEBUG_X"), "makego")控制 make.go 的 verbose 模式。
• CAMLI_DEBUG_UPLOADS（bool）：pkg/client 的额外上传日志，被 pkg/env/env.go 读取。
• CAMLI_DEBUG_IMAGES（bool）：pkg/images 解码图片时的额外调试输出，供索引器使用。
• CAMLI_SHA1_ENABLED（bool）：是否启用创建遗留 SHA-1 blob。仅用于开发期创建新 blob 时改用 SHA-1 哈希；不影响 Perkeep 读取已有 SHA-1 blob 的能力。devcam 的-sha1标志映射它（dev/devcam/server.go）。
• CAMLI_FAST_DEV（bool）：供 dev/demo.sh 做演示时使用，让 devcam server/put 等命令跳过make.go、直接使用预构建产物以加速启动。
• DEV_THROTTLE_KBPS（integer）与DEV_THROTTLE_LATENCY_MS（integer）：对 pkg/webserver 的响应做限速/注入延迟，值 0 表示关闭流量整形。devcam 的-slow标志注入默认值：150 kBps 与 90 ms（dev/devcam/server.go）。底层通过 go4.org/net/throttle 实现（pkg/webserver/webserver.go）。
• RUN_BROKEN_TESTS（bool）：运行已知损坏的测试，供维护者回归验证。

四、devcam 环境变量注入全景

devcam 是 Perkeep 的本地开发环境封装，它把上文大量变量集中注入到子进程，是理解"哪些变量由谁消费"的最佳入口。以devcam server为例，核心注入逻辑在 dev/devcam/server.go 的setEnvVars中：

1. 先注入客户端通用变量：CAMLI_AUTH、CAMLI_CACHE_DIR、CAMLI_CONFIG_DIR、CAMLI_SECRET_RING、CAMLI_KEYID、CAMLI_KV_VERIFY（dev/devcam/env.go）。
2. 依据-slow/-debug/-fullindexsync注入DEV_THROTTLE_KBPS、DEV_THROTTLE_LATENCY_MS、CAMLI_HTTP_DEBUG、CAMLI_FULL_INDEX_SYNC_ON_START。
3. 依据索引后端选项注入对应CAMLI_*INDEX_ENABLED与CAMLI_DBNAME。
4. 依据-publish/-scancab/-hello/-sha1注入CAMLI_PUBLISH_ENABLED、CAMLI_SCANCAB_ENABLED、CAMLI_HELLO_ENABLED、CAMLI_SHA1_ENABLED。
5. 注入CAMLI_BASEURL（由监听端口与 hostname 推导）、CAMLI_DEV_CAMLI_ROOT、以及一组 blob 根目录变量（CAMLI_ROOT、CAMLI_ROOT_SHARD1等）。

因此，如果你需要复刻"与 devcam 一致"的变量环境用于自定义启动脚本，可以直接参考该函数的注入清单，而不必逐条手工拼写。

五、待补充文档（Undocumented）变量清单

仓库文档明确标注以下变量尚未成文（在源码中可见，语义待补充）。了解其存在有助于 grep 代码时快速识别：

• CAMLI_API_HOST
• CAMLI_APP_LISTEN
• CAMLI_DEBUG_QUERY_SPEED
• CAMLI_DEV_MAP_CLUSTERING
• CAMLI_FAKE_STATUS_ERROR
• CAMLI_GPHOTOS_FULL_IMPORT
• CAMLI_MORE_FLAGS（文档中出现两次，疑为重复条目）
• CAMLI_PICASA_FULL_IMPORT
• CAMLI_QUIET
• CAMLI_REINDEX_START
• CAMLI_SERVER
• CAMLI_SET_BASE_URL_AND_SEND_ADDR_TO
• CAMLI_SYNC_VALIDATE
• CAMLI_TWITTER_FULL_IMPORT
• CAMLI_TWITTER_SKIP_API_IMPORT
• DEV_THROTTLE_KBPS/DEV_THROTTLE_LATENCY_MS（虽已在上文解释，文档仍将其列入待整理）
• PERKEEP_MASTODON_FULL_IMPORT

注意：CAMLI_SERVER虽然在文档"Undocumented"一节出现，但源码 pkg/client/config.go 中getServer已实际使用它——优先级最高于命令行标志与配置文件。CAMLI_GPHOTOS_FULL_IMPORT、CAMLI_PICASA_FULL_IMPORT、CAMLI_TWITTER_FULL_IMPORT等"全量导入"类变量与 pkg/importer 的导入器相关，grep 对应 importer 目录（如 pkg/importer/twitter、pkg/importer/picasa）即可看到实际消费点。

六、优先级总览与实战建议

综合以上解析，Perkeep 的配置优先级大体遵循"命令行标志 > 环境变量 > 配置文件 > 系统默认"的规律，但存在例外，需以具体变量为准：

实战建议：

• 测试场景：S3 测试用AWS_ACCESS_KEY_ID/AWS_ACCESS_KEY_SECRET；故障注入用CAMLI_S3_FAIL_PERCENT。
• 开发调试：组合使用CAMLI_DEBUG、CAMLI_HTTP_DEBUG、CAMLI_DEBUG_UPLOADS、CAMLI_DEBUG_CONFIG；网络问题用DEV_THROTTLE_KBPS/DEV_THROTTLE_LATENCY_MS复现慢速环境；性能剖析用CAMLI_PPROF_START。
• 索引开发：CAMLI_REDO_INDEX_ON_RECEIVE做局部回溯索引，CAMLI_KV_VERIFY追查 kv 损坏，CAMLI_MONGO_WIPE清空 mongo 索引。
• 迁移与兼容：从 Camlistore 升级到 Perkeep 时注意旧目录自动迁移提示（internal/osutil/paths.go），CAMLI_CACHE_DIR/CAMLI_CONFIG_DIR可显式指定以完全控制数据位置。

最后提醒：CAMLI_*前缀是历史遗留命名（Camlistore 时代），新代码同时支持PERKEEP_*（如PERKEEP_CACHE_DIR），迁移过程中两者保持兼容，引用时注意区分。

• 后端
• 数据存储