diff --git a/README.md b/README.md index 4dc37240d..9f1b0de04 100644 --- a/README.md +++ b/README.md @@ -464,6 +464,8 @@ or you can run in background nohup openviking-server > /data/log/openviking.log 2>&1 & ``` +For long-running environments, prefer a `systemd --user` service instead of `nohup` so restarts and process state are managed consistently. See: [Server Mode (systemd user service)](./docs/en/getting-started/03-quickstart-server.md#run-with-systemd-user-service-recommended-for-linux). + #### Run the CLI ```bash diff --git a/docs/en/getting-started/03-quickstart-server.md b/docs/en/getting-started/03-quickstart-server.md index 8396280a9..f8a0629c3 100644 --- a/docs/en/getting-started/03-quickstart-server.md +++ b/docs/en/getting-started/03-quickstart-server.md @@ -28,6 +28,37 @@ You should see: INFO: Uvicorn running on http://0.0.0.0:1933 ``` +## Run with systemd user service (recommended for Linux) + +`openviking-server` runs in the foreground. For persistent Linux sessions, use a user-level systemd unit instead of shell background wrappers. + +1. Copy the example unit file: + +```bash +mkdir -p ~/.config/systemd/user +cp docs/en/getting-started/examples/openviking-server.service ~/.config/systemd/user/openviking.service +``` + +2. Edit the unit values: + +- Set `WorkingDirectory` to your OpenViking workspace +- Set `Environment=OPENVIKING_CONFIG_FILE=...` to your `ov.conf` path +- Optionally add `Environment=OPENVIKING_CLI_CONFIG_FILE=...` if needed + +3. Enable and start: + +```bash +systemctl --user daemon-reload +systemctl --user enable --now openviking.service +systemctl --user status openviking.service +``` + +4. View logs: + +```bash +journalctl --user -u openviking.service -f +``` + ## Verify ```bash diff --git a/docs/en/getting-started/examples/openviking-server.service b/docs/en/getting-started/examples/openviking-server.service new file mode 100644 index 000000000..e6f358760 --- /dev/null +++ b/docs/en/getting-started/examples/openviking-server.service @@ -0,0 +1,15 @@ +[Unit] +Description=OpenViking Server (user service) +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +WorkingDirectory=%h/openviking +Environment=OPENVIKING_CONFIG_FILE=%h/.openviking/ov.conf +ExecStart=/usr/bin/env openviking-server --config ${OPENVIKING_CONFIG_FILE} +Restart=on-failure +RestartSec=2 + +[Install] +WantedBy=default.target diff --git a/docs/zh/getting-started/03-quickstart-server.md b/docs/zh/getting-started/03-quickstart-server.md index 683790609..f424a2367 100644 --- a/docs/zh/getting-started/03-quickstart-server.md +++ b/docs/zh/getting-started/03-quickstart-server.md @@ -28,6 +28,37 @@ openviking-server --port 1933 INFO: Uvicorn running on http://0.0.0.0:1933 ``` +## 使用 systemd 用户服务运行(Linux 推荐) + +`openviking-server` 默认以前台方式运行。对于需要长期驻留的 Linux 会话,建议使用 user-level systemd unit,而不是依赖 shell 后台包装。 + +1. 复制示例 unit 文件: + +```bash +mkdir -p ~/.config/systemd/user +cp docs/en/getting-started/examples/openviking-server.service ~/.config/systemd/user/openviking.service +``` + +2. 按实际环境修改 unit 配置: + +- 将 `WorkingDirectory` 改为 OpenViking 工作目录 +- 将 `Environment=OPENVIKING_CONFIG_FILE=...` 改为你的 `ov.conf` 路径 +- 如果需要 CLI 配置文件,可额外添加 `Environment=OPENVIKING_CLI_CONFIG_FILE=...` + +3. 启用并启动服务: + +```bash +systemctl --user daemon-reload +systemctl --user enable --now openviking.service +systemctl --user status openviking.service +``` + +4. 查看日志: + +```bash +journalctl --user -u openviking.service -f +``` + ## 验证 ```bash