pvince10/debian_dev

•Updated 6 months ago

Image

1.3K

pvince10/debian_dev repository overview

⁠debian_dev 镜像使用手册

基于 debian:12-slim 的全离线开发环境镜像，内置 Python（pyenv 多版本）、Node.js、Docker-in-Docker、SSH、code-server、AI CLI 工具，通过 supervisor 统一管理进程。

⁠目录

镜像版本⁠
基础版快速启动⁠
桌面版快速启动⁠
环境变量⁠
访问方式⁠
开发环境⁠
多用户管理⁠
代理配置⁠
frpc 内网穿透⁠
AI CLI 工具⁠
常见问题⁠

⁠1. 镜像版本

镜像 Tag	说明
`debian_dev:latest`	基础版（code-server + SSH + DinD）
`debian_dev:desktop`	桌面版（基础版 + Xfce4 + VNC + noVNC + RDP）

⁠2. 基础版快速启动

⁠创建数据目录

mkdir -p ./data/devbox/home ./data/devbox/docker

⁠docker-compose.yml 模板

services:
  devbox:
    image: debian_dev:latest
    container_name: devbox
    privileged: true
    restart: unless-stopped

    ports:
      - "22222:22"      # SSH
      - "28080:8080"    # code-server
      # - "3000:3000"
      # - "8000:8000"

    environment:
      - DEV_PASSWORD=changeme
      - CODE_SERVER_PASSWORD=changeme
      # - SSH_PUBLIC_KEY=ssh-rsa AAAA...
      # - SSH_PASSWORD_AUTH=no
      # frpc 内网穿透：配置 ./config/frpc.toml 后设为 true 自动启动
      # - FRPC_AUTOSTART=true

    volumes:
      - devbox-home:/home
      - devbox-docker:/var/lib/docker
      - ./config/frpc.toml:/opt/frpc/frpc.toml  # frpc 配置（宿主机管理）

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  devbox-home:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/devbox/home
  devbox-docker:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/devbox/docker

⁠启动

docker compose up -d

⁠3. 桌面版快速启动

⁠创建数据目录

mkdir -p ./data/devbox_desktop/home ./data/devbox_desktop/docker

⁠docker-compose.yml 模板

services:
  devbox-desktop:
    image: debian_dev:desktop
    container_name: devbox-desktop
    privileged: true
    restart: unless-stopped

    ports:
      - "22222:22"      # SSH
      - "28080:8080"    # code-server
      - "33389:3389"    # RDP
      - "36080:6080"    # noVNC

    environment:
      - DEV_PASSWORD=changeme
      - CODE_SERVER_PASSWORD=changeme
      - VNC_PASSWORD=changeme
      - RESOLUTION=1920x1080
      # - SSH_PUBLIC_KEY=ssh-rsa AAAA...
      # - SSH_PASSWORD_AUTH=no
      # frpc 内网穿透：配置 ./config/frpc.toml 后设为 true 自动启动
      # - FRPC_AUTOSTART=true

    volumes:
      - devbox-desktop-home:/home
      - devbox-desktop-docker:/var/lib/docker
      - ./config/frpc.toml:/opt/frpc/frpc.toml  # frpc 配置（宿主机管理）

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  devbox-desktop-home:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/devbox_desktop/home
  devbox-desktop-docker:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/devbox_desktop/docker

⁠启动

docker compose up -d

⁠4. 环境变量

⁠基础版

变量	默认值	说明
`DEV_PASSWORD`	`changeme`	SSH 登录密码
`CODE_SERVER_PASSWORD`	`changeme`	code-server 访问密码
`SSH_PUBLIC_KEY`	空	SSH 公钥（免密登录）
`SSH_PASSWORD_AUTH`	`yes`	`no` 则禁用密码登录，仅允许公钥
`FRPC_AUTOSTART`	`false`	`true` 则容器启动时自动运行 frpc

⁠桌面版（额外变量）

变量	默认值	说明
`VNC_PASSWORD`	`changeme`	VNC / noVNC 访问密码
`RESOLUTION`	`1920x1080`	桌面分辨率

⁠5. 访问方式

⁠基础版

方式	地址
SSH	`ssh -p 22222 coder@<host>`
code-server（浏览器）	`http://<host>:28080`

VS Code Remote SSH 配置（~/.ssh/config）：

Host devbox
    HostName <host>
    Port 22222
    User coder

⁠桌面版（额外访问方式）

方式	地址
noVNC（浏览器桌面）	`http://<host>:36080`
RDP（Windows 远程桌面）	`<host>:33389`，用户名 `coder`

⁠6. 开发环境

⁠Python（pyenv）

pyenv versions           # 查看已安装版本
pyenv install 3.11.7     # 安装新版本
pyenv global 3.11.7      # 设置全局默认
pyenv local 3.10.13      # 设置当前目录版本

# 虚拟环境（推荐 uv）
uv venv && source .venv/bin/activate
uv pip install fastapi

# 或使用 venv
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

⁠Node.js（nvm）

node -v             # 当前版本
nvm install 20      # 安装版本
nvm use 20          # 切换版本
nvm alias default 20
npm install express

⁠Docker（DinD）

容器内可直接使用 Docker，无需额外配置：

docker ps
docker build -t myapp .
docker run -d myapp

⁠7. 多用户管理

默认用户 coder（UID 1000）已内置。需要额外用户时，进入容器执行：

# 用法：adduser-dev <用户名> [UID] [密码]
adduser-dev dev2 1001 mypassword

# 省略 UID（自动分配）
adduser-dev dev3 "" mypassword

# 省略密码（默认 changeme）
adduser-dev dev4 1002

新用户自动加入 sudo 和 docker 组，继承 zsh + oh-my-zsh + pyenv + nvm 环境。

注意：手动创建的用户在容器重建后会消失，但 /home/<用户名> 数据保留在 volume 中，重建后重新执行 adduser-dev 即可恢复。

⁠8. 代理配置

⁠proxy_setting.sh（轻量代理）

每个用户 ~ 目录下有 proxy_setting.sh，通过 proxy 别名使用：

vim ~/proxy_setting.sh          # 填入代理地址和 API Key

proxy start                     # 开启系统代理
proxy start --host 192.168.1.x --port 7890
proxy stop                      # 关闭代理
proxy status                    # 查看状态

⁠clashctl（完整代理管理）

clash 已安装在 /opt/clashctl/，默认不自动加载。需要时编辑 ~/.zshrc，取消注释：

. "/opt/clashctl/scripts/cmd/clashctl.sh"

然后：

clashctl start
clashctl stop
clashctl status

⁠9. frpc 内网穿透

容器启动时自动创建默认 frpc 服务（supervisor 托管），配置文件 /opt/frpc/frpc.toml，所有用户可读写。

⁠默认服务

通过宿主机 ./config/frpc.toml 管理配置（已 volume 映射到 /opt/frpc/frpc.toml）：

vim ./config/frpc.toml

frpc.toml 配置示例：

serverAddr = "frp.example.com"
serverPort = 7000
auth.token = "your_token"

[[proxies]]
name = "devbox_ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 39487

[[proxies]]
name = "devbox_code-server"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8080
remotePort = 39488

# 桌面版额外端口（按需取消注释）
# [[proxies]]
# name = "devbox_rdp"
# type = "tcp"
# localIP = "127.0.0.1"
# localPort = 3389
# remotePort = 39489

# [[proxies]]
# name = "devbox_novnc"
# type = "tcp"
# localIP = "127.0.0.1"
# localPort = 6080
# remotePort = 39490

在 docker-compose.yml 中控制是否自动启动：

# 自动启动（默认 false，配置好后取消注释）
# - FRPC_AUTOSTART=true

手动控制：

docker exec -it devbox supervisorctl start  frpc-default
docker exec -it devbox supervisorctl stop   frpc-default
docker exec -it devbox supervisorctl status frpc-default
docker exec -it devbox tail -f /var/log/supervisor/frpc.log

⁠多用户独立 frpc

每个用户 ~/.config/frpc/ 下有独立配置模板：

vim ~/.config/frpc/frpc.toml    # 填入服务器地址、token、端口

# 手动运行
frpc -c ~/.config/frpc/frpc.toml

# supervisor 托管（自动保活）
sudo cp ~/.config/frpc/frpc-supervisor.conf \
        /etc/supervisor/conf.d/frpc-$(whoami).conf
sudo supervisorctl reread && sudo supervisorctl update
sudo supervisorctl start frpc-$(whoami)

⁠10. AI CLI 工具

三个 AI CLI 工具已全局安装：

claude    # Claude Code（Anthropic）
gemini    # Gemini CLI（Google）
codex     # Codex CLI（OpenAI）

配置 API Key：

export ANTHROPIC_AUTH_TOKEN=your_key
export GEMINI_API_KEY=your_key
export OPENAI_API_KEY=your_key

或通过 proxy_setting.sh 统一配置。

⁠11. 常见问题

Q：code-server 密码忘了？

docker exec devbox cat /home/coder/.config/code-server/config.yaml

Q：容器内 docker 命令报 permission denied？

groups   # 确认用户在 docker 组
# 重新登录 SSH 使组生效

Q：SSH 连接报 WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED？

重建容器后主机密钥会变，清除本地缓存：

ssh-keygen -R "[<host>]:22222"

Q：noVNC 黑屏或无法连接？

docker exec -it devbox-desktop supervisorctl status vncserver
docker exec -it devbox-desktop supervisorctl restart vncserver novnc
docker exec -it devbox-desktop tail -f /var/log/supervisor/vncserver.log

Q：如何查看各服务日志？

docker exec -it devbox supervisorctl status
docker exec -it devbox tail -f /var/log/supervisor/code-server.err.log

Tag summary

Recent tags

Content type

Image

Digest

sha256:07fb1221e…

Size

1.7 GB

Last updated

6 months ago

docker pull pvince10/debian_dev:desktop-v1.1.1-amd64