문제 해결 및 FAQ

빠른 진단 및 시스템 복구

Bluefin은 깨끗하고 안정적으로 동작하도록 설계되었지만, 문제가 생기더라도 이미지 기반 시스템은 간단한 롤백과 초기화 수단을 제공합니다.

시스템 롤백

커널이나 OS 업데이트로 문제가 생기면 이전 배포로 재부팅하거나 롤백하세요:

# Roll back to previous deployment
sudo bootc rollback

적용하려면 재부팅하세요. 현재 배포와 이전 배포의 상태를 확인하려면:

sudo bootc status

GNOME 및 확장 기능 초기화

데스크톱 확장 기능이나 셸 설정 변경으로 화면 문제나 오작동이 생기면:

# Reset GNOME Shell and extensions to system defaults
dconf reset -f /org/gnome/

디스크 공간 확보 및 사용하지 않는 런타임 정리

# Clean up dangling containers and unused Flatpak runtimes
ujust clean-system

버그 보고 및 수정 확인

무언가 고장 났거나 기기에서 문제가 생기면, 다음 세 가지 명령으로 진단 정보를 메인테이너에게 바로 전달할 수 있습니다:

명령	하는 일
`ujust report`	시스템 진단 정보를 수집하고, 민감한 데이터를 로컬에서 제거한 뒤, 내용이 채워진 GitHub 이슈를 엽니다.
`ujust confirm <issue>`	내 하드웨어에서도 기존 이슈가 발생함을 확인합니다. 중복 이슈를 만들지 않고 하드웨어 정보만 추가합니다.
`ujust verify <issue>`	새 이미지에 수정이 반영된 뒤, 내 하드웨어에서 이슈가 해결되었는지 확인합니다.

모든 보고서는 제출 전에 검토할 수 있도록 표시되고, 본인 소유의 gist에 저장되며, 자동화된 백그라운드 원격 측정(telemetry)은 절대 사용하지 않습니다.

키보드 레이아웃 및 입력 문제

키보드 레이아웃 전환 단축키가 Search Light와 충돌하는 경우

GNOME의 기본 전환 단축키(Super+Space)는 Search Light와 충돌합니다. 단축키를 바꾸려면:

Settings → Keyboard → Keyboard Shortcuts → View and Customize Shortcuts를 엽니다.
Typing을 클릭합니다.
Switch to next input source를 원하는 조합(예: Shift+Alt)으로 설정합니다.

확장 키보드 레이아웃(예: EurKEY)

Gnome Tweaks → Keyboard를 열고 Show Extended Input Sources를 On으로 켭니다.
로그아웃한 뒤 다시 로그인합니다.
Settings → Keyboard를 열고 **+**로 새 입력 소스를 추가한 다음 **More...**를 클릭해 원하는 레이아웃을 검색합니다.

입력기(IME / Fcitx5)

일반적인 키보드 레이아웃은 GNOME Help > Keyboard Layouts를 참고하세요. 한국어 등 아시아 언어나 기타 복잡한 입력 방식이 필요하다면:

Fcitx5 설치: flatpak install org.fcitx.Fcitx5
kimpanel GNOME 확장 기능을 설치합니다.
사용할 언어의 애드온을 설치합니다(예: flatpak install org.fcitx.Fcitx5.Addon.ChineseAddons).
Fcitx5 설정에서 입력기를 구성합니다. Ctrl+Space로 전환할 수 있습니다. 자세한 내용은 Fcitx 위키를 확인하세요.

자주 묻는 질문

Bluefin을 잘못 쓰고 있는 걸까요?

Don't hold Bluefin wrong

원하는 대로 써도 괜찮지만, Bluefin은 특정한 작업 방식을 염두에 두고 설계되었습니다:

개발 환경은 컨테이너로 분리하세요. OS와 섞어 쓰지 말고, Git으로 관리하는 devcontainer.json 파일로 프로젝트마다 정의하세요.
Flatpak과 Homebrew를 사용하세요. 핵심 OS 이미지는 변경하지 않고 두는 것이 이상적입니다.
파일을 재정의할 때는 XDG 표준을 따르세요. /etc, /var, /usr/local, /opt는 쓰기가 가능합니다. 사용자별 재정의는 대부분 ~/.config와 ~/.local에 있습니다.
오래된 방식의 지저분한 도구는 컨테이너에 격리하세요. 호스트에서 패키지를 직접 뜯어고치는 것은 안티패턴입니다.
재부팅을 너무 고민하지 마세요. 사용이 끝나면 PC를 끄거나 재부팅하세요. 스테이징된 OS 업데이트가 자동으로 적용됩니다.
하드웨어가 중요합니다. Bluefin은 Linux 친화적인 하드웨어에서 가장 잘 동작합니다.

팁

I have Become Legend.

-- Dominus Ghaul

그럼 누구를 위한 OS인가요?

Bluefin은 사용자가 현대적인 데스크톱을 통해 Linux를 처음 접해야 한다고 굳게 믿습니다. 시장은 이전 세대의 Linux 데스크톱 관습을 받아들이지 않았고, ChromeOS나 Android 같은 현대적인 모델이 성공했습니다. 사용자의 95%는 브라우저와 Flatpak만으로 충분합니다. Bluefin은 그 95%를 위해 관리가 필요 없는 OS로 설계되었으며, 개발자에게는 클라우드 네이티브 도구를 기본으로 제공합니다.

코덱은 어떻게 하나요?

필요한 것은 모두 Universal Blue를 통해 기본으로 포함되어 있습니다.

Homebrew는 왜 쓰나요?

Homebrew is Great on Linux를 확인하세요. Homebrew는 기본 이미지를 건드리거나 sudo를 쓰지 않고도 CLI 유틸리티를 관리합니다.

Bluefin 이미지는 왜 여러 개인가요?

Bluefin은 모든 이미지에서 동일하게 유지되도록 노력합니다. 차이는 업데이트 주기와 특화된 도구뿐입니다:

Bluefin: 일반 데스크톱 사용을 위한, 게이트 커널을 쓰는 현재 Fedora 기반 이미지.
Bluefin Server: FSDK 기반, DDI 우선의 최소 서버 OS.
Bluefin DX: 컨테이너와 devcontainer를 갖춘 개발자 작업 공간.

Ubuntu의 영향이 많이 보이는 이유는?

Bluefin의 공동 창립자 3명은 Canonical에서 Ubuntu 작업을 했습니다. Bluefin은 클래식 Ubuntu 데스크톱의 정신("Linux for Human Beings")을 현대적인 클라우드 네이티브 컨테이너 인프라 위에 되살립니다.

믿어도 되나요?

모든 것은 공개적으로 빌드되고, Cosign / GPG로 서명되며, GitHub Actions를 통해 게시됩니다. 배경은 Jorge Castro의 소개를 확인하세요.

Ask Bluefin 및 자동화된 진단

정보

이 기능은 알파 단계입니다. 메뉴 기능은 아직 없습니다.

Bluefin AI 페이지 - Bluespeed 계획에 대한 더 많은 배경 정보를 제공합니다

메뉴에서 "Ask Bluefin"을 선택하면 채팅 에이전트를 사용할 수 있습니다.

"Ask Bluefin"은 맞춤형 운영체제 에이전트입니다. 새 사용자에게는 인터넷을 뒤지거나 "배포판을 잘못 골랐다"는 훈수에 시달리지 않고 Linux를 배울 수 있도록 돕는 시스템입니다. "Ask Bluefin"은 운영체제와 그 문서로 학습되므로 항상 신뢰할 수 있는 출처에서 배우며, 커뮤니티가 함께 다듬어 갑니다. Linux 숙련자에게는 로컬 PC를 위한 강력한 진단 도구이며, 서버와 클러스터와의 통합도 내장되어 있습니다 ...

Ctrl+Alt+Shift+G로 빠른 실행을 호출하면 키 하나로 도움말 에이전트를 부를 수 있습니다:

바로 쓰는 설정: `ujust probe`

Bluefin에는 AI 문제 해결 세션을 설정하고 실행하는 자동화가 내장되어 있습니다:

ujust probe

ujust probe를 실행하면 자동으로:

Goose가 설치되어 있는지 확인합니다(없으면 Homebrew로 설치할지 묻습니다).
ublue-os/tap/linux-mcp-server가 없으면 설치합니다.
goose-mcp-setup으로 linux-tools가 활성화된 Goose 구성을 자동으로 작성합니다.
구성된 LLM 제공자를 확인하고 세션을 시작합니다.

수동 설치 및 구성

수동으로 설치하거나 macOS에서 설정하려면:

Bluefin / Linux
macOS

brew install ublue-os/tap/linux-mcp-server
goose-mcp-setup

brew install ublue-os/tap/linux-mcp-server
goose-mcp-setup

노트

macOS에서 linux-mcp-server는 SSH를 통해 원격 Linux 호스트를 점검합니다. ~/.config/goose/config.yaml의 envs에 LINUX_MCP_HOST: <host>를 설정하세요.

ublue-os/tap/linux-mcp-server를 설치하면 linux-mcp-server, Goose 클라이언트(block-goose-cli), goose-mcp-setup이 함께 설치됩니다.

linux-mcp-server

시스템 진단 및 모니터링 도구를 제공합니다:

시스템 정보(OS, 커널, 하드웨어)
프로세스 관리
서비스 모니터링(systemd)
로그 접근(journalctl)
네트워크 진단
파일 시스템 검사

저장소: rhel-lightspeed/linux-mcp-server

구성 단계

1단계: Goose 확장 구성

goose-mcp-setup을 실행하면 linux-tools 확장이 미리 구성된 ~/.config/goose/config.yaml이 만들어집니다:

extensions:
  linux-tools:
    enabled: true
    type: stdio
    name: linux-tools
    description: Linux system administration and diagnostics
    cmd: /home/linuxbrew/.linuxbrew/bin/linux-mcp-server
    envs:
      LINUX_MCP_USER: <your-username>
      LINUX_MCP_LOG_LEVEL: INFO
      LINUX_MCP_SSH_KEY_PATH: ~/.ssh/id_ed25519
    timeout: 30
    bundled: null
    available_tools: []
    args: []

2단계: LLM 제공자 구성

Goose는 호스팅 제공자와 로컬 모델을 모두 지원합니다. 다음을 실행하세요:

goose configure

GitHub Copilot: GitHub Copilot을 선택하면 GitHub 계정으로 바로 인증합니다.
호스팅 API: Anthropic, OpenAI, Gemini 등을 선택하고 안내에 따라 API 키를 입력하세요.
로컬 모델: llmman은 모델을 컨테이너로 관리하고 OpenAI 호환 엔드포인트를 제공합니다:

brew install llmmanorg/tap/llmman
llmman serve

~/.config/goose/config.yaml에서 Goose가 로컬 모델을 사용하도록 설정하세요:

GOOSE_PROVIDER: ollama
GOOSE_MODEL: qwen3:8b
OLLAMA_HOST: http://localhost:17434

LM Studio(brew install lm-studio)는 그래픽 대안입니다. 모델을 불러오고 로컬 서버를 시작한 다음 goose configure에서 LM Studio를 선택하세요.

3단계: 문제 해결 시작

대화형 세션을 시작하세요:

ujust probe
# or directly:
goose session

보안 고려 사항

MCP 서버는 현재 사용자 권한으로 실행됩니다
신뢰할 수 있는 출처의 MCP 서버만 설치하세요
서버 문서에서 필요한 권한을 검토하세요
민감한 자격 증명은 환경 변수로 전달하세요(구성 파일에 하드코딩하지 마세요)
보안 패치를 받을 수 있도록 MCP 서버를 정기적으로 업데이트하세요

더 읽을거리

자동화된 문제 해결

자연어로 시스템에 대해 도구에 물어볼 수 있습니다:

Top CPU usage

시스템 상태

참고: 아래 내용은 linux-mcp-server 페이지에서 가져온 것이지만, 어떤 걸 물어볼 수 있는지 감을 잡는 데 도움이 됩니다:

확인하려는 항목	사용할 도구	예시 프롬프트
OS / 커널	`get_system_information`	"이 OS 버전이 뭐야?"
CPU 부하	`get_cpu_information`	"CPU가 과부하 상태야?"
메모리 / RAM	`get_memory_information`	"남은 RAM이 얼마나 돼?"
디스크 공간	`get_disk_usage`	"가득 찬 디스크가 있어?"
하드웨어	`get_hardware_information`	"PCI 장치 목록을 보여줘."

문제 해결

확인하려는 항목	사용할 도구	예시 프롬프트
실행 중인 앱	`list_processes`	"CPU를 가장 많이 쓰는 게 뭐야?"
프로세스 세부 정보	`get_process_info`	"프로세스 ID 1234를 살펴봐줘."
서비스	`list_services`	"모든 서비스가 실행 중이야?"
서비스 상태	`get_service_status`	"nginx가 왜 실패했어?"
시스템 로그	`get_journal_logs`	"지난 1시간 동안의 오류를 보여줘."
서비스 로그	`get_service_logs`	"sshd의 최근 로그를 보여줘."
특정 로그 파일	`read_log_file`	"/var/log/messages의 마지막 50줄을 읽어줘."

네트워크

확인하려는 항목	사용할 도구	예시 프롬프트
IP 주소	`get_network_interfaces`	"내 IP 주소가 뭐야?"
열린 포트	`get_listening_ports`	"어떤 포트가 열려 있어?"
연결	`get_network_connections`	"22번 포트에 누가 연결돼 있어?"

파일 및 저장소

확인하려는 항목	사용할 도구	예시 프롬프트
디스크 파티션	`list_block_devices`	"파티션 구성을 보여줘."
큰 폴더	`list_directories`	"/var에서 가장 큰 폴더를 찾아줘."
최근 변경 사항	`list_files`	"/etc에서 최근에 바뀐 파일이 뭐야?"
파일 읽기	`read_file`	"/etc/fstab을 읽어줘."

유용한 팁

도구 조합하기: 한 번에 하나씩만 요청할 필요는 없습니다.

"CPU 사용량을 확인하고 상위 5개 프로세스를 보여줘."
로그 필터링: 시간과 우선순위를 구체적으로 지정하면 컨텍스트 창을 아낄 수 있습니다.

"지난 30분 동안의 error 우선순위 로그를 보여줘."
원격 호스트: SSH를 설정했다면 특정 호스트에서 실행하도록 요청하세요.

"webserver1의 디스크 사용량을 확인해줘."

troubleshooting

빠른 진단 및 시스템 복구​

시스템 롤백​

GNOME 및 확장 기능 초기화​

디스크 공간 확보 및 사용하지 않는 런타임 정리​

버그 보고 및 수정 확인​

키보드 레이아웃 및 입력 문제​

키보드 레이아웃 전환 단축키가 Search Light와 충돌하는 경우​

확장 키보드 레이아웃(예: EurKEY)​

입력기(IME / Fcitx5)​

자주 묻는 질문​

Bluefin을 잘못 쓰고 있는 걸까요?​

그럼 누구를 위한 OS인가요?​

코덱은 어떻게 하나요?​

Homebrew는 왜 쓰나요?​

Bluefin 이미지는 왜 여러 개인가요?​

Ubuntu의 영향이 많이 보이는 이유는?​

믿어도 되나요?​

Ask Bluefin 및 자동화된 진단​

바로 쓰는 설정: ujust probe​

수동 설치 및 구성​

linux-mcp-server​

구성 단계​

1단계: Goose 확장 구성​

2단계: LLM 제공자 구성​

3단계: 문제 해결 시작​

보안 고려 사항​

더 읽을거리​

자동화된 문제 해결​

시스템 상태​

문제 해결​

네트워크​

파일 및 저장소​

유용한 팁​

Contributors to this page