无头 Linux 后端

本页面面向云主机、家用服务器、实验室机器等无头 Linux 环境。目标是让 Jarvis 后端长期运行，并用浏览器从你的电脑访问它。

如果你只是在当前电脑上从源码试跑 Jarvis，使用 快速开始。

前置条件

• 一台 Linux 服务器，推荐 Ubuntu 24.04+。
• 可以 SSH 到服务器。
• git 和 curl 可用。
• Docker 路径需要 Docker Engine / Compose 可用；裸机路径需要 Python 3.11+、Node.js 20.19+ 和 systemd。
• 如果要从 Jarvis 启动编码会话，运行 Jarvis 后端的同一环境里必须能执行并已登录对应运行时 CLI，例如 Claude Code、Codex、OpenCode 或 Kimi Code。Docker 部署时，宿主机 CLI 不会自动出现在容器里。

不要把整个仓库变成 root 所有

用最终运行 Jarvis 的用户克隆仓库、编辑 .env 和维护 data/。系统包、Docker 或 systemd 需要管理员权限时，只对那些系统操作使用管理员权限；不要让 .venv、node_modules 或 data/ 变成 root 所有。

推荐：从你的电脑运行自托管 operator

如果这是无头服务器的首次部署，或者你不确定服务器有没有 sudo、Node 20.19+、python3-venv、Docker / systemd，先从你的电脑运行仓库里的 operator：

git fetch origin main

python3 scripts/selfhost.py doctor --host <ssh-host>
python3 scripts/selfhost.py deploy --host <ssh-host> --dry-run
python3 scripts/selfhost.py deploy --host <ssh-host>

python3 scripts/selfhost.py tunnel open --host <ssh-host> --local-port 18888 --remote-port 8888
python3 scripts/selfhost.py verify --url http://127.0.0.1:18888

这条路径默认远端目录是 ~/Jarvis，并部署本机可解析的 origin/main 精确 commit，不复制本机 dirty worktree 或 secrets。自定义远端路径时请加引号，例如 --remote-dir '~/Jarvis-test'，避免你的本机 shell 把 ~ 展开成本机 HOME。服务器无法访问 GitHub 时会回退到 git bundle；远端 Node 过旧时会在本机按 Model A 构建 frontend/dist 后上传；python3 -m venv 不可用时会尝试 user-space virtualenv。需要完全手工控制系统包、Docker 或 systemd 时，再走下面的传统路径。

1. 克隆并准备配置

在服务器上运行：

git clone https://github.com/12libao/Jarvis.git ~/Jarvis
cd ~/Jarvis

cp .env.example .env
printf '\nJARVIS_FORCE_HTTP=1\n' >> .env

编辑 .env，至少确认这些基础项：

JARVIS_PORT=8888
JARVIS_FORCE_HTTP=1
# 公网或共享服务器建议开启：即使请求来自 loopback，也要求 API key。
# JARVIS_AUTH_ALWAYS_REQUIRED=1

JARVIS_FORCE_HTTP=1 让源码启动脚本和 Docker 默认走 HTTP。裸机 systemd 模板也默认用 HTTP；但如果 .env 里设置了 JARVIS_SSL_CERTFILE / JARVIS_SSL_KEYFILE，systemd 会按证书参数启动 TLS。复用旧 .env 时先确认这些证书变量为空。

JARVIS_AUTH_ALWAYS_REQUIRED=1 会关闭本机回环请求的认证绕过。服务器暴露到公网、共享内网或多人使用时建议开启；只做个人内网测试时可以先保持默认。

2. 选择部署模式

Docker 是推荐的后端、聊天和远程访问路径；裸机 systemd 适合你想让 Jarvis 直接使用服务器用户的 Python 环境、模型缓存和本地 CLI 配置。

Docker（推荐）

bash deploy/setup-server.sh

脚本会生成 deploy/.env，构建镜像并启动 jarvis 容器。Docker compose 使用 host network，容器内 Jarvis 默认监听 JARVIS_PORT。

如果服务器还没有 Docker，请先按你的发行版方式安装 Docker Engine 和 Compose，再运行 setup 脚本。

Docker 镜像内置后端、Web、gh 和 cloudflared，但不内置 Claude Code、Codex、OpenCode 或 Kimi Code。需要编码会话时，要么把运行时 CLI 安装并登录到容器环境里，要么使用裸机 systemd 路径。

裸机 systemd

裸机 helper deploy/setup-server.sh --bare-metal 是一次性 provisioning 脚本：它会执行系统包安装并写入 /etc/systemd/system/jarvis.service。在普通用户拥有的 checkout 上，不要用 sudo bash deploy/setup-server.sh --bare-metal，否则 .venv、缓存或 data/ 容易变成 root 所有。

对普通部署用户，使用下面的手动路径，把系统操作和用户目录操作分开：

sudo apt-get update
sudo apt-get install -y python3-venv ripgrep git curl

python3 -m venv .venv
.venv/bin/python -m pip install -e 'backend/[dev]'

(cd packages/shared-mobile && npm ci --no-audit --no-fund)
(cd frontend && npm ci --no-audit --no-fund && npm run build)

SERVICE_USER="$(id -un)"
SERVICE_FILE="$(mktemp)"
sed "s|__REPO_DIR__|$PWD|g; s|__VENV_DIR__|$PWD/.venv|g; s|User=ubuntu|User=$SERVICE_USER|g" \
  deploy/jarvis.service.template > "$SERVICE_FILE"

sudo install -m 0644 "$SERVICE_FILE" /etc/systemd/system/jarvis.service
rm "$SERVICE_FILE"
sudo systemctl daemon-reload
sudo systemctl enable --now jarvis

这条手动路径不会预装 cloudflared；如果后续在 UI 里开启远程访问，应用会按需走兜底安装路径。

临时源码运行

如果你只需要在服务器上临时启动一个 headless 后端，而不是安装长期服务，可以使用 CLI 后台模式：

python3 -m venv .venv
.venv/bin/python -m pip install -e 'backend/[dev]'

DATA_DIR="$HOME/.jarvis-headless"
PORT=8888

.venv/bin/jarvis start \
  --no-open \
  --port "$PORT" \
  --data-dir "$DATA_DIR"

这个路径适合 API 或短期验证。它不会安装 systemd service，也不会替你维护 Docker 容器。所有内置启动器当前都会绑定 0.0.0.0；如果你必须只监听 127.0.0.1，需要自定义 uvicorn / systemd 启动命令，并自行承担后续维护。

3. 确认后端健康

在服务器上运行：

curl --noproxy '*' http://127.0.0.1:8888/api/v1/health

响应应为 JSON，并包含 status 和 version。如果你改了 JARVIS_PORT，把命令里的 8888 换成对应端口。

4. 生成 API 密钥

启动后端后生成一个浏览器用 API 密钥。密钥只显示一次，不要提交到仓库、issue 或截图里。

Docker

docker exec jarvis bash -lc 'jarvis genkey --data-dir "$JARVIS_REPO_DIR" -d "admin browser"'

裸机 systemd

.venv/bin/jarvis genkey -d "admin browser"

如果你使用了临时源码运行里的独立 DATA_DIR，生成 key 时必须使用同一个 data dir：

.venv/bin/jarvis genkey --data-dir "$DATA_DIR" -d "admin browser"

5. 从你的电脑打开服务器 UI

无头服务器没有本地浏览器。首次访问建议从你的电脑做 SSH 本地端口转发：

ssh -L 8888:127.0.0.1:8888 <user>@<server>

然后在你自己的电脑浏览器打开：

http://127.0.0.1:8888

粘贴刚生成的 API 密钥。如果你在服务器上使用了其他端口，把 SSH 命令左右两侧的 8888 一起改掉。

需要让 tunnel 在本机终端退出后继续保持时，用 operator 创建本机持久 tunnel：

python3 scripts/selfhost.py tunnel open --host <ssh-host> --local-port 18888 --remote-port 8888

macOS 会写入当前用户的 LaunchAgent；Linux 会优先写 user systemd service。两者都只绑定 127.0.0.1，不会把本机端口暴露到局域网。

为什么优先用 SSH 转发

start.sh 和 Docker 入口都会让后端监听 0.0.0.0，所以内网直连可以工作。但 SSH 转发让首次登录、API key 粘贴和远程访问绑定都发生在你自己的 localhost 上，避免裸公网 IP、代理或浏览器安全策略带来的额外变量。

6. 可选：开启远程访问

如果你要从手机或外网浏览器访问这台服务器，先通过上面的 SSH 转发打开本地 UI，然后在 Jarvis 里开启远程访问。绑定完成后，使用官方入口：

https://jarvis.xcos.dev/app

不要直接打开裸隧道子域。裸隧道地址绕过托管入口的认证和路由层，常见表现是登录、API 或 WebSocket 一直失败。

cloudflared 通常已经由部署流程准备好：Docker 镜像内置；裸机 setup 会安装到仓库的 data/bin/；应用内远程访问入口也有兜底安装路径。

7. 日常运维

Docker

docker logs -f jarvis
docker restart jarvis

cd ~/Jarvis/deploy
docker compose up -d --build

裸机 systemd

systemctl status jarvis
journalctl -u jarvis -f
sudo systemctl restart jarvis

从仓库根目录运行 ./restart.sh 时，如果检测到 jarvis.service 正在运行，会自动委托给 systemd restart / stop / reload。

更新源码后使用仓库自带脚本：

bash deploy/deploy-server.sh

它会自动判断 Docker / systemd 模式，拉取代码、按需重建、重启，并执行健康检查。

如果服务器上的 GitHub 访问、Node 或 Python 环境不稳定，改用本机 operator 的 deploy 子命令；它会先诊断再选择远端 git、git bundle、本机预构建前端或 virtualenv fallback。

常见问题

现象	先检查
curl 没有返回 JSON	端口是否与 JARVIS_PORT 一致，服务是否仍在启动。
浏览器打不开	先用 SSH 转发访问 http://127.0.0.1:8888，再排查防火墙或安全组。
裸机 systemd 起不来	User= 是否是实际部署用户，.venv / data/ 是否被 root 拥有。
前端过期或空白	Docker 重新 compose up -d --build；裸机确认 Node 版本后重跑前端 npm ci / npm run build，再 sudo systemctl restart jarvis。
API 密钥无效	后端数据库是否已经创建，是否在正确部署模式里生成 key。
远程入口转圈	不要打开裸隧道子域；通过 SSH 转发回 localhost 完成一次远程访问绑定。

相关页面

• 部署轨道
• 重启与健康检查
• 配置参考
• 排障