Cobalt 自建实例完全指南：Docker Compose 部署、Node.js 本地开发与全量环境变量配置

Cobalt 自建实例完全指南Docker Compose 部署、Node.js 本地开发与全量环境变量配置【免费下载链接】cobaltbest way to save what you love项目地址: https://gitcode.com/GitHub_Trending/cob/cobalt本篇技术指南基于 Cobalt 官方文档 run-an-instance.md 编写讲解如何自建一个 Cobalt 媒体下载实例覆盖 Docker Compose 推荐部署流程、Node.js 本地开发模式含 Ubuntu 22.04 的 DNS 修复方案、cookies.json 认证配置以及 API 与 Web 两套实例的全部环境变量。读完本文你可以独立完成一个可公开访问或仅限本地使用的 Cobalt 实例部署并根据源码级实现细节正确配置端口、CORS、限流、时长上限与代理等参数。两种部署方式的选择Cobalt 采用同一份代码库、两种运行角色的设计一次部署只能扮演API 实例处理下载请求或Web 实例提供前端界面中的一个两者可分开独立部署。这一行为由入口文件 src/cobalt.js 中的模式判定逻辑决定仅设置了API_URL没有WEB_URL→ 以 API 模式启动runAPI同时设置了WEB_URL和API_URL→ 以 Web 模式启动runWeb两者皆无 → 打印红色错误提示要求先运行npm run setup完成配置。src/modules/config.js 中的判定表达式可以确认这一点mode (apiURL !webEnvs.webURL) ? API : (webEnvs.webURL apiURL) ? WEB : undefined因此官方文档推荐两种部署路径Docker Compose推荐用于生产与Node.js 直接运行适合本地开发。方式一使用 Docker Compose 部署推荐前置条件安装并配置好docker与docker-compose即可按照任何标准 Docker 安装教程完成第一步Docker 本体安装与第二步Compose 安装。Cobalt 官方镜像基于 Dockerfile 构建基础镜像为node:18-bullseye-slim构建时安装 git 与构建工具、执行npm ci最终通过CMD [ node, src/cobalt ]启动入口EXPOSE 9000暴露 API 端口。部署步骤为 Cobalt 配置创建一个专用目录mkdir cobalt进入该目录并创建 Compose 配置文件nano不可用时可换用其他编辑器cd cobalt nano docker-compose.yml将 docs/examples/docker-compose.example.yml 的示例内容复制进去可只部署 web 或 api也可以两者都部署并务必把默认 URL 替换为你自己的实例域名否则 Cobalt 无法正确工作。从 cobalt 目录启动容器docker compose up -d官方示例 Compose 配置解析docs/examples/docker-compose.example.yml 定义了三个服务cobalt-api、cobalt-web与watchtower核心结构如下services: cobalt-api: image: ghcr.io/imputnet/cobalt:7 restart: unless-stopped container_name: cobalt-api init: true # 若容器无法以分离模式运行取消下一行注释 #tty: true ports: - 9000:9000/tcp # 使用反向代理时改为绑定回环地址并删除上一行 #- 127.0.0.1:9000:9000 environment: # 替换为你的实例 API 目标地址 API_URL: https://api.cobalt.tools/ # 替换为你的实例标识名称 API_NAME: eu-nl # 需要 cookies 时取消注释并同时启用下方 volume # COOKIE_PATH: /cookies.json labels: - com.centurylinklabs.watchtower.scopecobalt # 使用 cookies 时取消注释 #volumes: #- ./cookies.json:/cookies.json cobalt-web: image: ghcr.io/imputnet/cobalt:7 restart: unless-stopped container_name: cobalt-web init: true ports: - 9001:9001/tcp # 使用反向代理时改为 #- 127.0.0.1:9001:9001 environment: # 替换为你的实例前端地址 WEB_URL: https://cobalt.tools/ # 前端客户端发起 API 请求时使用的地址 API_URL: https://api.cobalt.tools/ labels: - com.centurylinklabs.watchtower.scopecobalt # watchtower 自动更新 cobalt 镜像 watchtower: image: ghcr.io/containrrr/watchtower restart: unless-stopped command: --cleanup --scope cobalt --interval 900 --include-restarting volumes: - /var/run/docker.sock:/var/run/docker.sock几个值得注意的要点API 与 Web 端口分离API 监听9000Web 监听9001与 src/modules/config.js 中的默认值apiPort: process.env.API_PORT || 9000、webPort: process.env.WEB_PORT || 9001一一对应watchtower 自动更新示例中 watchtower 以--scope cobalt --interval 900 --cleanup --include-restarting运行即每 900 秒检查一次 scope 为cobalt的容器是否有新镜像并自动重启替换——这就是官方文档所说“cobalt 包会借助 watchtower 自动更新”的实现机制反向代理支持文档强烈建议在实例面向公网时使用 nginx 等反向代理。此时应将端口映射改为127.0.0.1:9000:9000Web 同理让服务只绑定回环地址由代理统一对外。方式二使用 Node.js 直接运行本地开发此方式适合本地开发。官方 setup 脚本会安装全部npm依赖但你需要自行安装Node.js18 及以上版本package.json 中engines声明为node: 18和git。克隆仓库git clone https://gitcode.com/GitHub_Trending/cob/cobalt运行 setup 脚本并按提示交互npm run setup启动实例npm startpackage.json 中对应的脚本为setup: node src/modules/setup与start: node src/cobalt。setup 脚本做了什么src/modules/setup.js 是一个交互式配置向导它会依次询问并生成.env文件实例类型api或web二者必须选其一——即“API 与 Web 实例需分别部署”API 模式询问域名默认localhost非 localhost 时拼接为https://domain/、端口默认9000、实例名默认local、是否启用 CORS默认否即CORS_WILDCARD0Web 模式询问域名默认http://localhost:9001/、端口默认9001、前端默认对接的 API 地址默认https://api.cobalt.tools/最后写入.env并自动执行npm install提示运行npm start即可。脚本还提示可随时重新运行以更新配置。Ubuntu 22.04 的 DNS 故障绕过方案在 Ubuntu 22.04 上以 Node.js 方式运行时需要安装并启动nscd服务否则ffmpeg-static二进制无法完成 DNS 解析官方 issue 中记录的已知问题sudo apt install nscd sudo service nscd start支持需登录内容cookies.json 配置若希望实例支持那些“需要认证才能查看公开内容”的服务如 Instagram、Reddit、Twitter 等在与docker-compose.yml同目录下创建cookies.json文件。格式参见 docs/examples/cookies.example.json按服务名分组的键值结构如下{ instagram: [ midreplace; ig_didwith; csrftokenyour; ds_user_idown; sessionidcookies ], instagram_bearer: [ tokentoken_with_no_bearer_in_front, tokenIGT:2:looks_like_this ], reddit: [ client_idreplace_this; client_secretreplace_this; refresh_tokenreplace_this ], twitter: [ auth_tokenreplace_this; ct0replace_this ] }在 Docker 环境中还需完成两步联动配置取消environment中COOKIE_PATH: /cookies.json的注释同时取消volumes中- ./cookies.json:/cookies.json的挂载。源码侧对应 src/modules/config.js 中的cookiePath: process.env.COOKIE_PATHAPI 实例专属配置项。环境变量全量参考API 实例环境变量变量名默认值示例说明API_PORT90009000API 服务器可访问的端口。API_LISTEN_ADDRESS0.0.0.0127.0.0.1API 服务器监听地址。使用 Docker 时通常无需配置此项。API_URL➖无默认https://api.cobalt.tools/API 服务器的对外访问地址。运行 API 必需。API_NAMEunknownams-1显示在/api/serverInfo中的 API 服务器名称。API_EXTERNAL_PROXY➖http://user:password127.0.0.1:8080传给 undiciProxyAgent的代理地址所有对外请求经此代理。仅支持 HTTP(S)。CORS_WILDCARD10切换跨域资源共享0禁用、1启用。CORS_URLnot usedhttps://cobalt.tools允许跨域访问的来源地址仅当CORS_WILDCARD0时 API 只对该地址开放。COOKIE_PATHnot used/cookies.jsonCookie 文件相对于主目录的路径。PROCESSING_PRIORITYnot used10修改 ffmpeg 子进程的nice值数值越大优先级越低仅 Unix 系统可用。FREEBIND_CIDR➖2001:db8::/32为 Cobalt 请求随机分配地址所用的 IPv6 前缀仅 Linux 系统支持详见下文。RATELIMIT_WINDOW60120限流时间窗口单位秒。RATELIMIT_MAX2030每个时间窗口内允许的最大请求数超出即被拦截至窗口结束。DURATION_LIMIT1080018000允许的最大视频时长单位秒。上表的默认值均可在 src/modules/config.js 的apiEnvs对象中得到印证例如rateLimitWindow: (process.env.RATELIMIT_WINDOW parseInt(process.env.RATELIMIT_WINDOW)) || 60, rateLimitMax: (process.env.RATELIMIT_MAX parseInt(process.env.RATELIMIT_MAX)) || 20, durationLimit: (process.env.DURATION_LIMIT parseInt(process.env.DURATION_LIMIT)) || 10800,限流与 CORS 的源码实现限流在 src/core/api.js 中通过express-rate-limit落地普通 API 与 stream 端点各挂一个限流器windowMs取RATELIMIT_WINDOW * 1000秒转毫秒、max取RATELIMIT_MAX并暴露Ratelimit-Limit、Ratelimit-Policy、Ratelimit-Remaining、Ratelimit-Reset四个标准响应头超限请求返回429其中/api/json会附带本地化错误文案。CORS 逻辑同样在此文件当CORS_WILDCARD不为0默认启用时corsConfig为空对象即放行所有来源否则配置{ origin: env.corsURL, optionsSuccessStatus: 200 }把跨域访问限制在CORS_URL指定的单一地址上。/api/serverInfo返回的信息中也包含cors: Number(env.corsWildcard)前端可据此判断实例的跨域策略。FREEBIND_CIDR 深入说明设置FREEBIND_CIDR后Cobalt 会为每个下载任务随机挑选一个 IP并用它承载该次下载产生的所有请求——从源码结构看这是一种基于 IPv6 前缀的出口地址随机化机制。使用该功能的前提先完成 freebind 库的底层 setup内核模块与 freebind 工具的配置package.json 将freebind列为optionalDependencies版本^0.2.2而 src/modules/config.js 中freebindCIDR: process.platform linux process.env.FREEBIND_CIDR表明该选项仅在 Linux 平台生效若在 Docker 容器中启用还必须把API_LISTEN_ADDRESS设为127.0.0.1并将容器的network_mode设为host。Web 实例环境变量变量名默认值示例说明WEB_PORT90019001前端服务器可访问的端口。WEB_URL➖无默认https://cobalt.tools/前端服务器的对外访问地址。运行 Web 必需。API_URLhttps://api.cobalt.tools/https://api.cobalt.tools/前端客户端发起 API 请求时使用的地址。SHOW_SPONSORS01切换关于弹窗中的赞助者列表0关闭、1开启。IS_BETA01切换 Cobalt Logo 旁的 beta 标签0关闭、1开启。PLAUSIBLE_HOSTNAME➖plausible.io*以给定主机名作为接收后端启用 plausible 统计分析。* 除非付费使用其云服务否则不要直接把plausible.io作为接收后端自建 plausible 社区版时应填自己的域名。遗留环境变量名的自动迁移src/modules/sub/alias-envs.js 在入口启动前会执行一组遗留变量名到新变量名的映射apiPort → API_PORT、apiURL → API_URL、apiName → API_NAME、cors → CORS_WILDCARD、cookiePath → COOKIE_PATH、webPort → WEB_PORT、webURL → WEB_URL、showSponsors → SHOW_SPONSORS、isBeta → IS_BETA。若检测到旧名而新名未设置会自动迁移并在控制台输出红色弃用警告。如果你沿用旧版实例的.env文件可以平滑过渡到新命名。小结关键核对清单Docker 部署确认已替换API_URL/WEB_URL为自己域名公网暴露时改绑127.0.0.1并配置反向代理watchtower 服务负责自动更新镜像Node.js 部署Node.js ≥ 18npm run setup生成.env后npm start启动Ubuntu 22.04 记得安装nscd必需项API 实例必须提供API_URLWeb 实例必须提供WEB_URL否则 src/cobalt.js 会判定为“未配置”并拒绝启动认证服务cookies.jsonCOOKIE_PATH 容器卷挂载三者缺一不可容量与公平性参数RATELIMIT_WINDOW/RATELIMIT_MAX/DURATION_LIMIT的默认值60 秒 / 20 次 / 10800 秒适合一般自用场景公开实例可参考 docs/examples/docker-compose.example.yml 的方式按需调整。【免费下载链接】cobaltbest way to save what you love项目地址: https://gitcode.com/GitHub_Trending/cob/cobalt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考