code-server란 무엇인가 — 서버에서 브라우저로 VS Code 쓰는 법과 헷갈리기 쉬운 것들

서버에서 포트를 확인하다가 8080이 올라와 있는 걸 발견했다. 웹 서비스 Next.js는 3333인데 8080은 뭐지? 알고 보니 code-server였다.

---

📌 code-server가 뭔가

VS Code를 서버에 설치해서 브라우저로 접근하는 웹 IDE다.

로컬 PC에 VS Code를 따로 설치하지 않아도, 브라우저 주소창에 http://서버IP:8080만 입력하면 익숙한 VS Code 환경이 그대로 뜬다.

처음 발견했을 때 이런 의문이 생겼다.

"이걸 내가 원하는 서비스 포트에 어떻게 매핑하는 거지?"

결론부터 말하면 매핑할 게 없다.

code-server는 서비스와 연결되는 프록시가 아니라, 서버 파일시스템에 직접 접근하는 브라우저용 에디터다. 실행 중인 서비스와 별개로 독립적으로 동작한다.

---

📌 code-server를 왜 쓰나

일반적인 서버 작업 방식과 비교하면 차이가 명확하다.

방식 특징 불편한 점

SSH + vim/nano	터미널에서 직접 편집	에디터 기능 제한, 익숙하지 않으면 불편
로컬 편집 → Git push → 서버 pull	안전하고 이력 관리 가능	사소한 수정도 commit/push 과정 필요
SFTP/SCP로 파일 전송	파일을 로컬에서 편집 후 업로드	동기화 번거로움
code-server	브라우저에서 VS Code 그대로 사용	Git 수동 관리 필요

특히 이런 상황에서 유용하다.

• 서버에 직접 접속해서 긴급 수정이 필요할 때
• 원격 서버 환경에서 로컬 개발환경처럼 작업하고 싶을 때
• 여러 PC나 태블릿에서 동일한 개발 환경을 쓰고 싶을 때
• 로컬 PC 성능이 부족하고 서버 리소스를 활용하고 싶을 때

---

📌 code-server를 쓸 수 없는 환경

반대로 이런 환경이나 상황에서는 적합하지 않다.

상황 이유

포트 외부 오픈이 불가한 환경	8080 포트가 방화벽에 막혀있으면 브라우저 접근 불가
보안 정책이 엄격한 프로덕션 서버	외부에서 코드 편집 가능한 웹 인터페이스 자체가 보안 위협
서버 리소스가 매우 부족한 환경	code-server 자체가 Node.js 프로세스로 메모리를 상당히 사용
Docker 컨테이너 내부	컨테이너 철학(불변 인프라)과 충돌. 컨테이너 안에서 직접 수정하는 방식은 지양
팀 협업 환경	누가 언제 서버에서 직접 수정했는지 추적이 어려워 혼선 발생 가능

---

📌 어떻게 설치하나

공식 설치 스크립트 한 줄이면 끝난다.

curl -fsSL https://code-server.dev/install.sh | sh

설치 후 systemd 서비스로 등록해서 서버 재부팅 시에도 자동으로 올라오게 한다.

# 현재 유저 기준으로 서비스 등록 및 즉시 시작
sudo systemctl enable --now code-server@$USER

이렇게 하면 /etc/systemd/system/code-server@{유저명}.service 파일이 생성되고, 부팅 시 자동 실행된다.

실행 상태 확인

systemctl status code-server@{유저명}

● code-server@nkshop.service - code-server
     Loaded: loaded (/etc/systemd/system/code-server@nkshop.service; enabled)
     Active: active (running) since Mon 2026-02-23 17:41:52 KST
   Main PID: 625 (node)

enabled 상태면 재부팅 후에도 자동 시작된다. 기본 포트는 8080이다.

# 포트 점유 확인
ss -tlnp | grep node

---

📌 소스코드와 어떻게 연동되나

별도 연동 설정이 필요한 게 아니다. 같은 파일시스템을 보고 있는 것이 전부다.

/프로젝트 디렉토리/
        ↑                      ↑
  pm2(Next.js)가           code-server가
  읽고 실행하는 파일       브라우저에서 편집하는 파일

code-server에서 파일을 수정하고 저장하면, Next.js가 변경을 감지해서 자동으로 반영된다.

로컬 PC의 VS Code + 터미널로 작업하는 것과 완전히 동일한 구조를 브라우저에서 하는 것이다.

양방향으로 반영되는 이유도 같다.

code-server와 pm2가 동일한 디렉토리의 파일을 바라보고 있기 때문에, 어느 쪽에서 수정하든 결과는 같다.

• 로컬에서 push → 서버에서 pull → 파일 변경
• code-server에서 직접 수정 → 파일 변경

둘 다 결국 같은 파일이 바뀌는 것이다.

---

📌 프로세스 구조 정리

systemd
└── code-server@nkshop.service  ← 부팅 시 자동 시작
    ├── node (code-server 메인)
    └── node (ptyHost — 브라우저 터미널 세션)

pm2
└── next-server (:3333)         ← Next.js 앱

두 프로세스는 서로 독립적으로 관리된다.

프로세스 관리 주체 포트 역할

code-server	systemd	8080	브라우저 IDE
Next.js	pm2	3333	웹 서비스

code-server를 끄더라도 Next.js 서비스에는 영향이 없고, Next.js를 재시작해도 code-server는 그대로다.

---

⚠️ 처음 쓰는 사람이 헷갈리는 포인트들

"code-server에서 코드를 수정하면 서비스에 바로 반영된다고?"

맞다. 단, 이건 code-server의 기능이 아니다.

code-server는 파일을 저장했을 뿐이고, 변경을 감지해서 자동으로 재시작하는 건 Next.js의 Hot Reload 기능이다.

Hot Reload란?

개발 서버가 파일 변경을 감지하면 자동으로 재빌드하고 브라우저를 갱신하는 기능이다.

Next.js는 next dev 명령으로 실행했을 때 기본으로 활성화된다.

PM2로 실행할 경우에는 watch 옵션을 설정해야 파일 변경 시 자동으로 재시작된다.

# PM2에서 파일 변경 감지 + 자동 재시작
pm2 start npm --name next-app --watch -- start

// ecosystem.config.js에서 설정
module.exports = {
  apps: [{
    name: 'next-app',
    script: 'npm',
    args: 'start',
    watch: true,          // 파일 변경 감지 활성화
    ignore_watch: ['node_modules', '.next'],  // 감지 제외 디렉토리
  }]
}

반대로 이런 경우에는 저장해도 바로 반영되지 않는다.

• next start(프로덕션 모드)로 실행 중인 경우 → Hot Reload 없음
• PM2에서 watch: false(기본값)로 설정된 경우 → 수동 재시작 필요
• 빌드가 필요한 변경사항(설정 파일, 환경변수 등)인 경우

# 프로덕션 환경에서 변경 후 수동으로 재시작해야 반영됨
pm2 restart next-app

---

"code-server에서 수정한 내용이 Git repo와 달라지면?"

code-server는 Git을 자동으로 관리하지 않는다. 파일시스템에 직접 저장할 뿐이다.

code-server에서 코드를 수정하면 이런 상태가 된다.

서버 파일 (수정됨)
    ↑
    └─ Git repo랑 다른 상태 → git status에서 modified로 표시됨

이 상태에서 누군가 git pull을 하면 충돌이 발생할 수 있다.

code-server로 서버에서 직접 파일을 수정한 뒤에는 반드시 아래 흐름을 지켜야 repo와 서버 파일이 일치 상태를 유지한다.

# code-server 터미널에서 git 상태 확인
git status
git diff

# 변경사항 커밋 후 push
git add .
git commit -m "fix: 긴급 수정"
git push origin main

---

"code-server에서 수정했는데 CI/CD 배포가 돌면 어떻게 되나?"

CI/CD(예: Bamboo, GitHub Actions)가 git pull이나 새로운 빌드 결과물로 파일을 덮어쓰면, code-server에서 직접 수정한 내용은 사라진다. 이게 가장 위험한 시나리오다.

code-server에서 직접 수정 (커밋 안 함)
        ↓
CI/CD 파이프라인 실행 (git pull or 빌드 배포)
        ↓
수정 내용 덮어쓰기 → 유실 ❌

code-server는 임시 디버깅·긴급 수정 용도로 쓰고, 실제 변경사항은 반드시 Git을 통해 관리하는 것이 원칙이다. 서버에서 직접 수정한 내용을 커밋하지 않은 채 방치하면 다음 배포 때 날아간다.

---

"code-server가 node 프로세스로 뜨는 이유가 뭔가?"

code-server 자체가 Node.js로 만들어진 애플리케이션이기 때문이다.

VS Code도 Electron 기반(Node.js + Chromium)으로 만들어졌고, code-server는 그 VS Code를 서버에서 node 프로세스로 실행하는 구조다.

그래서 ps aux | grep node나 ss -tlnp | grep node에서 code-server가 node 프로세스로 잡히는 게 정상이다.

# node 프로세스 중 code-server인지 확인
ps aux | grep code-server

---

📋 정리

항목 내용

code-server란	VS Code를 서버에서 실행해 브라우저로 접근하는 웹 IDE
기본 포트	8080
프로세스 관리	systemd (code-server@{유저명}.service)
서비스 연동 방식	별도 연동 없음. 같은 파일시스템을 공유할 뿐
수정 즉시 반영	code-server 기능 아님. Next.js Hot Reload 또는 PM2 watch 옵션 필요
Git과의 관계	자동 관리 안 함. 직접 수정 후 commit/push 필요
CI/CD와 충돌	배포가 덮어쓰면 미커밋 변경사항 유실. 반드시 커밋 후 방치 금지
쓰기 어려운 환경	방화벽으로 포트 막힌 경우, 보안 민감 서버, Docker 컨테이너, 팀 협업 환경
node 프로세스로 뜨는 이유	code-server 자체가 Node.js로 만들어진 앱이기 때문