에이전트 설치

사전 조건

에이전트는 Node.js 20 이상이 필요합니다. CRM 서버 설정에서 서버를 등록하면 토큰과 endpoint가 포함된 설치 안내가 표시됩니다. 토큰은 발급 직후 한 번만 표시되므로 안전한 곳에 복사하세요.

Ubuntu, systemd

# Ubuntu (Node.js 20+ 필요)
sudo npm i -g @the-seeker/server-agent@latest
sudo theseeker-agent install --token <token> --endpoint <endpoint> --user $USER
# macOS
npm i -g @the-seeker/server-agent@latest
theseeker-agent install --token <token> --endpoint <endpoint>

<endpoint>에는 API 응답의 agentEndpoint, 기본값 wss://ingest.theseeker.io/agent/ws를 사용합니다. Linux의 install은 root 권한이 필요합니다. root가 아니면 파일을 쓰지 않고 수동 명령을 출력한 뒤 exit code 2를 반환합니다. 에이전트 프로세스 자체는 sudo 없이 서비스 사용자로 실행됩니다.

설치 상태는 Ubuntu에서 sudo theseeker-agent status --user $USER, macOS에서 theseeker-agent status --user $USER로 확인합니다.

macOS에서는 sudo를 붙이지 않습니다. LaunchAgent는 GUI 로그인 세션에 연결되며 부팅 전용 daemon이 아닙니다.

nvm 전용 호스트

root PATH에 Node.js가 없다면 로그인 사용자로 먼저 패키지를 설치합니다.

npm i -g @the-seeker/server-agent@latest
sudo "$(command -v node)" "$(command -v theseeker-agent)" install --token <token> --endpoint wss://ingest.theseeker.io/agent/ws --user $USER

생성되는 systemd ExecStart에는 절대 Node 경로가 포함됩니다.

로그 권한

nginx나 journald를 읽어야 하면 install 명령에 --add-groups를 추가합니다. 또는 사용자를 adm, systemd-journal 그룹에 넣은 뒤 서비스를 재시작합니다.

PM2 감시 설정

--user에는 PM2 daemon을 소유한 사용자를 지정합니다. PM2 소유자는 ps -eo user,cmd | grep "PM2 v"로 확인할 수 있습니다. 서비스 사용자가 다르면 에이전트가 빈 PM2를 보거나 다른 PM2 인스턴스를 읽습니다.

PM2_HOME 환경 변수와 --pm2-home 옵션은 PM2 state가 있는 위치를 지정합니다. nvm 전용 호스트에서는 @the-seeker/[email protected] 이상의 install이 실행 중인 node 바이너리의 bin 디렉터리를 systemd PATH 앞에 자동으로 기록합니다. unit에는 Environment=PATH=<node bin dir>:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin이 들어가므로 nvm으로 설치한 PM2를 별도로 PATH에 추가할 필요가 없습니다. @the-seeker/[email protected]부터 pm2 jlist 대신 $PM2_HOME/rpc.sock RPC로 수집하며, 소켓이 없으면 빈 목록, 권한 오류면 permission_denied, 그 밖의 오류일 때만 jlist로 폴백합니다. 예전 방식은 PM2_COLLECTOR=jlist로 강제할 수 있습니다.

문제 해결

PM2 프로세스가 0개로 보임

서비스 사용자가 PM2 소유자인지 ls -la $PM2_HOME/rpc.sock과 ps -eo user,cmd | grep "PM2 v"로 확인합니다. --user는 PM2 데몬 소유자여야 하며, 설치할 때 지정한 --pm2-home이 실제 PM2 state와 rpc.sock이 있는 위치인지도 확인합니다.

PM2 미설치로 표시됨

로그인 사용자로 pm2 list가 되는데 대시보드에 PM2 미설치가 표시되면 systemd PATH에서 nvm의 PM2 경로가 빠진 경우일 수 있습니다. ExecStart의 절대 Node 경로 때문에 에이전트는 실행되지만, sibling binary인 pm2를 찾지 못해 capability가 not_installed가 됩니다.

0.1.1 이상으로 업그레이드하고 같은 토큰으로 install을 다시 실행합니다. 기존 토큰은 /etc/theseeker-agent/config.json에 mode 600으로 보관되어 있으며 sudo로 읽을 수 있습니다.

npm i -g @the-seeker/server-agent@latest
sudo "$(command -v node)" "$(command -v theseeker-agent)" install --token <token> --endpoint wss://ingest.theseeker.io/agent/ws --user <pm2 owner user>
sudo systemctl restart theseeker-agent

같은 토큰으로 다시 실행해도 0.1.1은 unit과 설정만 다시 쓰고 실행 중인 서비스를 재시작하지 않습니다(enable --now는 실행 중이면 no-op). 이어서 sudo systemctl restart theseeker-agent를 실행해야 하며, 0.1.2부터는 install이 자동으로 재시작합니다. 업그레이드하지 않는 경우에는 systemd drop-in으로 PM2_BIN을 지정한 뒤 재시작합니다.

sudo systemctl edit theseeker-agent

[Service]
Environment=PM2_BIN=/home/<user>/.nvm/versions/node/<ver>/bin/pm2

sudo systemctl restart theseeker-agent

로그 열기가 permission_denied

PM2 out/err 로그가 ~/.pm2/logs 밖에 있어도 일반 파일이면 tail할 수 있습니다. 예를 들어 /home/theseeker/tradingrecipe-consumer/logs/*.log가 가능합니다. 로그 경로가 허용된 루트(/var/log/nginx, <PM2_HOME>/logs, ~/.pm2/logs) 밖을 가리키는 symlink이면 permission_denied가 반환됩니다.