# Linux 通用配置

# myzsh 安装与配置

### Check the env

```
cat /etc/shells 

```

[![](http://www.netflt.com/uploads/images/gallery/2024-08/scaled-1680-/TxQN9Vo7JYQbvuKm-image-1723181940883.png)](http://www.netflt.com/uploads/images/gallery/2024-08/TxQN9Vo7JYQbvuKm-image-1723181940883.png)

### Install zsh

```
sudo apt-get install zsh
## replace zsh as default shell manager
sudo chsh -s $(which zsh) $USER

```

[![](http://www.netflt.com/uploads/images/gallery/2024-08/scaled-1680-/LWnBH59Litac4Bu3-image-1723181948839.png)](http://www.netflt.com/uploads/images/gallery/2024-08/LWnBH59Litac4Bu3-image-1723181948839.png)

### Install oh-my-zsh

```
sudo apt-get install wget
sudo apt-get install git

wget https://github.com/robbyrussell/oh-my-zsh/raw/master/tools/install.sh -O - | sh

```

[![](http://www.netflt.com/uploads/images/gallery/2024-08/scaled-1680-/oyFLmvZwtcxuP0L2-image-1723181959516.png)](http://www.netflt.com/uploads/images/gallery/2024-08/oyFLmvZwtcxuP0L2-image-1723181959516.png)

### Install plugin

```

git clone https://github.com/zsh-users/zsh-autosuggestions $ZSH_CUSTOM/plugins/zsh-autosuggestions

git clone https://github.com/zsh-users/zsh-syntax-highlighting.git $ZSH_CUSTOM/plugins/zsh-syntax-highlighting

```

### Edit myzsh theme

```
vim ~/.zshrc
##add plugin
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)
### select a theme
ZSH_THEME="ys"
source ~/.zshrc 

```

### Install autojump

```
sudo apt-get install autojump

# add autojump.zsh in .zshrc
. /usr/share/autojump/autojump.zsh





```

### oh-my-zsh 在 `git` 目录下执行命令会卡顿明显，简单的 `cd` 和 `ls` 都会。

> ##### 原因:
> 
> 插件会读取 git 的配置信息，如果项目目录下有太多的文件，卡顿会非常明显。可以使用以下命令禁止 zsh 自动获取 git 信息，解决卡顿问题：
> 
> ##### 解决：
> 
> 1. 设置 oh-my-zsh 不读取文件变化信息  
>     git config --add oh-my-zsh.hide-dirty 1
> 2. 设置 oh-my-zsh 不读取任何 git 信息  
>     git config --add oh-my-zsh.hide-status 1
> 3. 全局设置 oh-my-zsh 不读取文件变化信息  
>     git config --global oh-my-zsh.hide-dirty 1
> 4. 全局设置 oh-my-zsh 不读取任何 git 信息  
>     git config --global oh-my-zsh.hide-status 1

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/OHMt4bXvftK8cexY-image-1735725824393.png)](http://www.netflt.com/uploads/images/gallery/2025-01/OHMt4bXvftK8cexY-image-1735725824393.png)

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/8u2s8LMO7mmSPtWY-image-1735726419540.png)](http://www.netflt.com/uploads/images/gallery/2025-01/8u2s8LMO7mmSPtWY-image-1735726419540.png)

# SSH 免密登陆

原文链接：[https://blog.csdn.net/weixin\_43922901/article/details/106078558](https://blog.csdn.net/weixin_43922901/article/details/106078558)

该方法和什么终端无关，主要是根据ssh key方式登陆，无需远程主机登录密码，非常方便。

### 1 生成ssh秘钥和公钥文件

进入本地终端：

```
ssh-keygen -t rsa

```

出现如下图所示，这时候请不要一直回车，输入相应的文件名称，因为不输入的话是默认生成id\_rsa和id\_rsa.pub两个文件。然而，由于很多人其实在本地配置了GitHub的钥匙，因此会存在这样的文件，所以在这里我们需要改个名，比如id\_ssh。

[![](/uploads/images/gallery/2024-08/scaled-1680-/KVPrbNd01ZvA4Rmb-image-1723127521085.png)](/uploads/images/gallery/2024-08/KVPrbNd01ZvA4Rmb-image-1723127521085.png)

输入秘钥文件名：

[![](/uploads/images/gallery/2024-08/scaled-1680-/9L6d6nynDn9uEGaP-image-1723127534556.png)](/uploads/images/gallery/2024-08/9L6d6nynDn9uEGaP-image-1723127534556.png)

输入完钥匙文件名称后，在路径~/.ssh/下会生成文件id\_ssh和id\_ssh.pub

[![](/uploads/images/gallery/2024-08/scaled-1680-/a7stlBNBS4D7tRAQ-image-1723127559322.png)](/uploads/images/gallery/2024-08/a7stlBNBS4D7tRAQ-image-1723127559322.png)

然后执行：

```
cat id_ssh.pub

```

**把文件中的公钥复制到远程主机的~/.ssh/authorized\_keys中**，如果没有这个文件，那么请创建一个新的。

[![](/uploads/images/gallery/2024-08/scaled-1680-/lyFY68zVz3Ng2ug2-image-1723127576215.png)](/uploads/images/gallery/2024-08/lyFY68zVz3Ng2ug2-image-1723127576215.png)

### 2 配置config文件

同样**进入到本地 .ssh目录**

```
cd ~/.ssh/ 
vim config

```

按如下格式修改目录下的config文件。有几个主机就可以配置几个，但是本地的id\_ssh.pub内的公钥内容一定记得复制到远程主机的~/.ssh/authorized\_keys中。

```
Host workhost0  # 远程主机别名
  HostName 192.168.63.8  # 远程主机ip
  User zhangsan  # 你在远程主机的用户名
  Port 22
  IdentityFile ~/.ssh/id_ssh  # 你的ssh秘钥文件

Host workhost1
  HostName 192.168.63.9
  User zhangsan
  Port 22
  IdentityFile ~/.ssh/id_ssh

```

### 3 登录

在本地终端执行：

```
ssh workhost0

```

即可成功免密登录。

# Nginx 安装及配置

### 安装nginx

```bash
wget http://soft.vpser.net/lnmp/lnmp1.6.tar.gz -cO lnmp1.6.tar.gz 
tar zxf lnmp1.6.tar.gz 
cd lnmp1.6 
./install.sh nginx

```

### 添加网站

```bash
lnmp vhost add

```

### 代理HTTP

```bash
server {
    listen       80;
    server_name  www.netflt.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header REMOTE-HOST $remote_addr;
    }
}

```

### 代理HTTPS

```bash
server {
    listen 443 ssl;
    server_name netflt.com;
    ssl_certificate /home/ubuntu/lisence/netflt.com.crt;
    ssl_certificate_key /home/ubuntu/lisence/netflt.com.key;
    ssl_session_cache builtin:1000 shared:SSL:10m;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
    ssl_prefer_server_ciphers on;

    location / 
    {
        proxy_pass http://localhost:8181;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header REMOTE-HOST $remote_addr;
    }
}

```

# 基于 LazyVim 将 nvim 打造成 c++ IDE

工欲善其事,必先利其器. (以下这部分时废话)

从事 C++ 开发这么多年,一直都在用 vscode 作为 IDE, 其插件丰富以及优雅的 UI 交互让人爱不释手.直到有一天发现身边同事用 nvim 一通行云流水的操作,让我意识到自己过去的开发过程中,实际操作效率并不高.于是我决定有必要开始做些改变. 目前开源有不少非常优秀的 nvim 插件管理项目开箱即用,对于小白来说非常友好.但由于其默认集成了了不少通用插件,导致 nvim 启动的时候不够丝滑. 并且这些通用插件又未必都是你需要的,这时候你可能需要了解一些自定义安装插件的方法. 这几天花了一些时间将 nvim 打造成 c++ 开发利器,中间遇到不少坑,总结了些配置,仅供参考.

---

### 下载并安装 nvim

主要参考官方手册: https://github.com/neovim/neovim/blob/master/INSTALL.md

#### macos

```bash
brew install neovim

```

#### linux

```
sudo apt-get install neovim

```

### 基于 LazyVim 安装初始版本

如果你之前已经安装过 nvim, 为了保险起见,可以先备份或者删除;但确保本次启动前你的配置目录是干净的;

#### 备份原有配置(必须)

```
mv ~/.config/nvim{,.bak}

```

#### 备份插件及缓存(可选)

```
mv ~/.local/share/nvim{,.bak}
mv ~/.local/state/nvim{,.bak}
mv ~/.cache/nvim{,.bak}

```

#### 克隆官方给的 starter, 这个项目只是一个空壳,主要是用于安装 lazy 以及默认的一些插件

```
git clone https://github.com/LazyVim/starter ~/.config/nvim

```

#### 删除 .git 目录,后续你可以创建为自己的 git repo

```
rm -rf ~/.config/nvim/.git
nvim

```

首次启动效果如下:

[![](http://wiki.netflt.com/uploads/images/gallery/2024-09/scaled-1680-/LgMyEuzyTMdfSO3a-image-1725162687947.png)](http://wiki.netflt.com/uploads/images/gallery/2024-09/LgMyEuzyTMdfSO3a-image-1725162687947.png)

### 接下来开始配置插件

lazyvim 安装完后,默认的目录结构如下,其中 config 目录下的文件是固定的,不可改变;每个文件对应的功能也有对应的解释,这里不再赘述. Plugins 目录是用来自定义插件的,这里的文件名无所谓, lazyvim 会自动扫描这个目录下的所有文件并尝试加载;

[![](http://wiki.netflt.com/uploads/images/gallery/2024-09/scaled-1680-/wpZoo7vTew5KAXdY-image-1725163248700.png)](http://wiki.netflt.com/uploads/images/gallery/2024-09/wpZoo7vTew5KAXdY-image-1725163248700.png)

#### 自定义主题

这里已经有一个 `example.lua`,从这里入手,将文件改名为 `default.lua`; 并安装自己喜欢的主题, 默认使用的是 `tokyonightly`; 个人更喜欢 `github_dark`;

```
-- Plugins/default.lua
return {
  { "projekt0n/github-nvim-theme" },
  {
    "LazyVim/LazyVim",
    opts = {
      colorscheme = "github_dark",
    },
  },
}

```

效果如下: [![](http://wiki.netflt.com/uploads/images/gallery/2024-09/scaled-1680-/qvXqVmUMDybZlAoE-image-1725164007425.png)](http://wiki.netflt.com/uploads/images/gallery/2024-09/qvXqVmUMDybZlAoE-image-1725164007425.png)

#### 设置 tab 宽度并显示空格,

```
-- config/options.lua
-- utf8
vim.g.encoding = "UTF-8"

-- 缩进4个空格等于一个Tab
vim.opt.tabstop = 4
vim.opt.softtabstop = 4

-- >> << 时移动长度
vim.opt.shiftwidth = 4

-- 空格替代tab
vim.opt.expandtab = true

-- 不可见字符的显示，这里只把空格显示为一个点
vim.opt.listchars = "space:·"

-- 默认关闭保存文件时自动格式化
vim.g.autoformat = false


```

[![](http://wiki.netflt.com/uploads/images/gallery/2024-09/scaled-1680-/YEW6NKzjxmaLyvvD-image-1725165239230.png)](http://wiki.netflt.com/uploads/images/gallery/2024-09/YEW6NKzjxmaLyvvD-image-1725165239230.png)

#### neo-tree 配置

默认情况下,neo-tree 不显示隐藏的文件和目录,但有时候我们是需要的;

```
return {
  "nvim-neo-tree/neo-tree.nvim",
  opts = {
    filesystem = {
        filtered_items = {
            visible = true,
            show_hidden_count = true,
            hide_dotfiles = false,
            hide_gitignored = true,
            hide_by_name = {
                --'.git', '.DS_Store',  -- 'thumbs.db',
            },
            never_show = {'.git'},
        },
    }
  }
}


```

# 在 docker 中打造 ubuntu 开发环境

#### 拉取 ubuntu image

```
docker pull ubuntu

```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/mnOrW9LUP0IdMi5l-image-1735723850572.png)](http://www.netflt.com/uploads/images/gallery/2025-01/mnOrW9LUP0IdMi5l-image-1735723850572.png)

#### 查看 image 是否存在

```
docker images

```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/RDOH4Y65ZAwYvFrW-image-1735715227640.png)](http://www.netflt.com/uploads/images/gallery/2025-01/RDOH4Y65ZAwYvFrW-image-1735715227640.png)

#### 启动容器

```
docker run --name ubuntu-dev -t -i -d -p 3316:22 ubuntu:latest

```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/HAsxFSNFP7E7Egcl-image-1735723968943.png)](http://www.netflt.com/uploads/images/gallery/2025-01/HAsxFSNFP7E7Egcl-image-1735723968943.png)参数说明:

- –name 指定生成的容器的名称
- -i: 以交互模式运行容器，保证容器中STDIN是开启的。通常与 -t 同时使用；
- -t: 为容器重新分配一个伪tty终端，通常与 -i 同时使用；
- -d: 后台运行容器，并返回容器ID；
- -p:可以指定要映射的IP和端口，但是在一个指定端口上只可以绑定一个容器。支持的格式有 hostPort:containerPort、ip:hostPort:containerPort、 ip::containerPort。
- ubuntu 则是镜像名称/版本，镜像ID也可以的。

#### 设置 root password

```
passwd root


```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/0EQgApM5CTSbCQ5A-image-1735724555302.png)](http://www.netflt.com/uploads/images/gallery/2025-01/0EQgApM5CTSbCQ5A-image-1735724555302.png)

#### 创建 sudo 用户

```
# 更新源并安装 vim
apt-get update
apt-get install vim

# 安装 sudo
apt-get install sudo

# 创建用户
adduser danny

# 添加到 sudo 分组
usermod -aG sudo danny



```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/9lJWfOmBrhjqCciP-image-1735724818337.png)](http://www.netflt.com/uploads/images/gallery/2025-01/9lJWfOmBrhjqCciP-image-1735724818337.png)

#### 安装 ssh 服务

```
apt-get install openssh-client -y
apt-get install openssh-server -y

```

### 设置端口, 并启动 ssh 服务

```
vim /etc/ssh/sshd_config
service ssh start

```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/GanhxAJNlITZFVLU-image-1735724426703.png)](http://www.netflt.com/uploads/images/gallery/2025-01/GanhxAJNlITZFVLU-image-1735724426703.png)[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/roSj37LxlO1aZthO-image-1735715627500.png)](http://www.netflt.com/uploads/images/gallery/2025-01/roSj37LxlO1aZthO-image-1735715627500.png)

### 配置 zsh,

参看: http://www.netflt.com/books/linux/page/myzsh-1xF

# neonvim 安装与配置

### 基于 cmd 安装, (有可能版本会比较旧)

```
sudo apt-get install neovim

```

### 基于源码安装

```
## install gcc build env
sudo apt-get install build-essential
sudo apt-get install cmake

### could not find luajit
sudo apt-get install luajit

## Could NOT find Gettext
sudo apt-get install gettext libgettextpo-dev

# get source
git clone https://github.com/neovim/neovim.git

cd neovim

#switch stable branch
gco stable

make CMAKE_BUILD_TYPE=RelWithDebInfo

sudo make install

```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/F9BxQ9kk9e1OOAeh-image-1735727423884.png)](http://www.netflt.com/uploads/images/gallery/2025-01/F9BxQ9kk9e1OOAeh-image-1735727423884.png)

### 下载 nvim 配置

```
mkdir -p ~/.config/
git clone https://github.com/netflt/nvim-cpp.git nvim
nvim ./

```

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/MoqNEglRVbxKjFm3-image-1735727673990.png)](http://www.netflt.com/uploads/images/gallery/2025-01/MoqNEglRVbxKjFm3-image-1735727673990.png)

> 可能出现以下错误原因是 blink\_cmp\_fuzzy 依赖文件找不到
> 
> 1. curl 没有安装导致 blink\_cmp\_fuzzy 下载失败; 可以安装 curl 重新启动 nvim 解决
> 2. libblink\_cmp\_fuzzy 找不到对应的版本,可以手动编译

[![](http://www.netflt.com/uploads/images/gallery/2025-01/scaled-1680-/8sD69dXoqthAdq9m-image-1735727637439.png)](http://www.netflt.com/uploads/images/gallery/2025-01/8sD69dXoqthAdq9m-image-1735727637439.png)

# 基于源码安装 gdb

> nvim-dap 依赖 gdb 建议使用 gdb-14.2, (低版本不支持 dap协议,而高版本可能提示 set breakpints not stopped)

```
wget https://ftp.gnu.org/gnu/gdb/gdb-14.2.tar.gz
tar xf gdb-14.2.tar.gz
cd gdb-14.2

mkdir build
cd build
../configure --enable-targets=all --with-expat --with-python=/usr/bin/python3

## error: Building GDB requires GMP 4.2+, and MPFR 3.1.0+.
sudo apt-get install libmpc-dev

## makeinfo: not found
sudo apt-get install texinfo 

##编译期间可能会遇到各类依赖错误,可以选择安装
sudo apt-get install flex bison libreadline-dev


make
sudo make install

```

# NVM 管理多版本 Node.js

##### nvm（Node Version Manager）是一个非常有用的工具，可以让您在同一台机器上安装和管理多个 Node.js 版本。

![](https://www.runoob.com/wp-content/uploads/2025/05/1_20ffnM3_eVpgVGGAbpuDjg.png)

### 为什么需要 nvm？

- 不同项目可能需要不同版本的 Node.js
- 测试应用在不同 Node.js 版本下的兼容性
- 方便升级和降级 Node.js 版本

### 安装 nvm

**在 macOS/Linux 上安装 nvm：**

```
# 使用 curl 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

# 或使用 wget 安装
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc
# 或
source ~/.zshrc
```

**在 Windows 上安装 nvm-windows：**

1. 下载 nvm-windows：[https://github.com/coreybutler/nvm-windows/releases](https://github.com/coreybutler/nvm-windows/releases)
2. 下载 nvm-setup.zip
3. 解压并运行安装程序

**nvm 常用命令：**

```
# 查看 nvm 版本
nvm --version

# 列出所有可安装的 Node.js 版本
nvm list-remote
# Windows 上使用
nvm list available

# 安装最新的 LTS 版本
nvm install --lts

# 安装特定版本
nvm install 18.17.0
nvm install 16.20.1

# 列出已安装的版本
nvm list
# 或
nvm ls

# 切换到特定版本
nvm use 18.17.0

# 设置默认版本
nvm alias default 18.17.0

# 查看当前使用的版本
nvm current

# 卸载特定版本
nvm uninstall 16.20.1
```

**实际使用示例：**

```
# 场景：为不同项目使用不同 Node.js 版本

# 项目 A 使用 Node.js 18
cd project-a
nvm use 18.17.0
node --version  # v18.17.0

# 项目 B 使用 Node.js 16
cd ../project-b
nvm use 16.20.1
node --version  # v16.20.1

# 为项目指定 Node.js 版本
echo "18.17.0" > .nvmrc
nvm use  # 自动使用 .nvmrc 中指定的版本
```

### 验证安装是否成功

**创建第一个 Node.js 程序：**

创建一个名为 `hello.js` 的文件：

**实例**

```
// hello.js
console.log('Hello, Node.js!');
console.log('Node.js 版本:', process.version);
console.log('当前工作目录:', process.cwd());
console.log('操作系统:', process.platform);
```

<div class="example" id="bkmrk--1"></div>**预期输出：**

```
Hello, Node.js!
Node.js 版本: v18.17.0
当前工作目录: /Users/username/projects
操作系统: darwin
```

**检查全局安装路径：**

```
# 查看 npm 全局包安装路径
npm config get prefix

# 查看 npm 配置
npm config list

# 查看 Node.js 安装路径
which node
# Windows 上使用
where node
```

# 基于 SSH Tunnel 打造自动化全链路代理网络

在终端中使用 AI 工具（如 OpenCode CLI）时，由于网络原因，我们经常需要配置代理。然而，OpenCode 底层的运行时对长连接、流式传输（Streaming）以及代理协议有极为严苛的要求。如果你直接使用 `ssh -D` 建立的 SOCKS5 代理，或者在环境变量中误加了 `http://` 前缀，就会频繁遭遇以下底层报错：

```
Cannot connect to API: The socket connection was closed unexpectedly
UnsupportedProxyProtocol fetching "https://moonshot.cn"

```

本文将带你一步步排查这些深坑，并利用 Linux 的 Systemd 将 SSH 动态转发与 HTTP-to-SOCKS 转换器打造成一个高可用、全自动、开箱即用的系统级服务链。

## 🛠️ 第一部分：痛点分析与核心避坑原理

### 1. 为什么 SSH 代理容易闪断？

OpenCode 与 AI 接口通信采用的是 HTTP Chunked Stream（流式传输）。当模型在思考（如 DeepSeek-R1 或复杂 Tool Call）时，通道会有数十秒没有任何数据。默认的 SSH 连接没有保活机制，中间的路由器或防火墙会判定连接超时，直接发送 RST 包断开 Socket。

### 2. 为什么会报 UnsupportedProxyProtocol？

OpenCode 底层依赖的特定运行时，其内置的 `fetch()` 代理逻辑不接受带协议头的环境变量（例如 `http://127.0.0.1:8080` 会被判定为非法协议）。正确的做法是只提供纯主机名与端口（`127.0.0.1:8080`）。

### 3. 网络拓扑设计

为了完美的兼容性，我们需要搭建如下的转发链路：

```
OpenCode CLI
   │ (环境变量: 127.0.0.1:8080)
   ▼
[本地 8080 端口] ── (http-proxy-to-socks 转换)
   ▼
[本地 1080 端口] ── (SSH -D 动态转发通道)
   ▼
[远程 SSH 服务器] ── (直连) ──> AI API (如 Moonshot / OpenAI)

```

## 🚀 第二部分：全链路自动化服务配置指南

### 前提条件

在开始前，请确保你已经配置好了 SSH 免密公钥登录。在终端执行 `ssh user@remote_server_ip` 时不需要手动输入密码。

### 步骤一：创建基础 SSH 常驻服务

首先，我们将普通的 SSH 动态转发命令打造成一个具备自动心跳保活、死服自动重启的 Systemd 系统服务。

创建服务文件：

```bash
sudo vim /etc/systemd/system/ssh-proxy.service

```

粘贴以下配置（请根据注释将 `your_username` 等信息替换为你本机的真实信息）：

```ini
[Unit]
Description=SSH SOCKS5 Proxy Service
After=network.target

[Service]
Type=simple
# 替换为你本机的真实 Linux 用户名
User=your_username
# -N: 不执行远程命令; -D: 开启 SOCKS5 端口; ServerAliveInterval: 每15秒发送心跳防止断连
ExecStart=/usr/bin/ssh -N -D 1080 -o ServerAliveInterval=15 -o StrictHostKeyChecking=no -i /home/your_username/.ssh/id_rsa user@remote_server_ip
# 核心：网络波动断开后，5秒后无限自动重连
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

```

### 步骤二：安装并创建 HTTP 协议转换服务

为了让不支持 SOCKS5 协议或对协议头敏感的工具完美运行，我们需要将 SOCKS5 转换为纯 HTTP 代理。

全局安装转换工具（避免在 Systemd 中使用不稳定的 npx）：

```bash
sudo npm install -g http-proxy-to-socks

```

检查安装路径：

```bash
which hpts
# 假设输出为 /usr/local/bin/hpts

```

创建转换服务文件：

```bash
sudo vim /etc/systemd/system/http-to-socks.service

```

粘贴以下配置，利用 `Requires` 和 `After` 声明服务依赖，让两个服务形成捆绑：

```ini
[Unit]
Description=HTTP to SOCKS Proxy Converter
# 强依赖：声明必须在 SSH 代理服务启动成功后，本服务才启动
After=ssh-proxy.service
Requires=ssh-proxy.service

[Service]
Type=simple
User=your_username
# 将本地 1080 的 SOCKS5 代理桥接到本地 8080 的 HTTP 代理
ExecStart=/usr/local/bin/hpts -s 127.0.0.1:1080 -p 8080
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

```

### 步骤三：一键激活服务生态链

得益于 Systemd 的依赖机制，你现在只需要启动最上层的 `http-to-socks` 服务，系统就会自动拉起底层的 SSH 代理。

```bash
# 刷新 Systemd 守护进程配置
sudo systemctl daemon-reload

# 允许开机自启并立即运行 HTTP 转换服务
sudo systemctl enable --now http-to-socks

# 检查运行状态（看到绿色 active (running) 即代表全链路打通）
sudo systemctl status http-to-socks

```

## 💻 第三部分：终端环境配置与测试

现在，底层的代理网络已经默默在后台守候。我们最后需要让 OpenCode CLI 认得这条路径。

打开你的终端配置文件（如 `~/.bashrc` 或 `~/.zshrc`）：

```bash
vim ~/.bashrc

```

在文件末尾追加以下环境变量。注意：绝对不要在 `HTTPS_PROXY` 里加 `http://` 前缀！

```bash
# 规避 UnsupportedProxyProtocol 报错的正确写法
export HTTPS_PROXY=127.0.0.1:8080
export HTTP_PROXY=127.0.0.1:8080
# 必须为本地 TUI 通信设置绕过，防止路由回环
export NO_PROXY=localhost,127.0.0.1
# 针对大模型思考耗时，延长本地客户端超时容错（单位：毫秒，此处为10分钟）
export API_TIMEOUT_MS=600000

```

保存退出，并刷新终端：

```bash
source ~/.bashrc

```

接下来，直接在终端里输入 `opencode` 启动。你会发现，无论是流式打字输出，还是长时间的复杂推理，都变得如丝般顺滑，再也不会弹出恼人的 Socket 关闭报错。

## 🔍 第四部分：日常维护与故障排查

查看链路是否正常通畅：

```bash
curl -I --proxy 127.0.0.1:8080 https://moonshot.cn

```

如果返回了 API 服务的 HTTP 状态码（如 401 或 405 均可，只要不是 Connection Refused），说明代理完全成功。

查看 SSH 是否断线或在重连：

```bash
sudo journalctl -u ssh-proxy -f

```

彻底关闭整个代理集群：

```bash
sudo systemctl stop http-to-socks

```

通过这套方案，我们不仅解决了当前工具的报错，还为本地终端搭建了一个极其稳健的代理基础设施，后续任何对网络环境挑剔的 CLI 工具，都可以直接复用这个 `127.0.0.1:8080` 端口。

# Mac M系列芯片 (ARM64) 基于 Docker-Compose 高性能部署宝塔面板技术方案

本文件详细记录了在搭载 Apple Silicon（M1/M2/M3/M4 系列）芯片、16G 内存、512G 固态硬盘的 Mac 宿主机上，利用 Docker 技术栈进行企业级、高性能宝塔开发环境的声明式部署与调优全流程。

---

## 🛠️ 一、 方案架构设计与优势

在 Mac ARM 架构下，本方案摒弃了传统的端口映射（Bridge）模式与第三方封装镜像，采用 **“官方纯净镜像 + Host网络 + 宿主机 Rosetta 2 转译”** 的企业级组合拳：

- **Host 网络模式 (免端口映射)：** 彻底解决最新版宝塔面板“随机 5 位数独立端口”无法提前映射的矛盾。容器直接共享 Mac 网络栈，宝塔内任何新增端口（如多站点、Redis、Node.js）无需重启 Docker 即可在 Mac 直接访问。
- **文件读写性能优化 (`:cached`)：** 抹平 macOS 与 Linux 容器间跨界文件读写的性能损耗，确保本地代码编辑器（如 VS Code）修改代码时，浏览器刷新无延迟。
- **Rosetta 2 二进制转译：** 针对宝塔内部极个别未提供原生 ARM64 版本的旧插件，提供接近原生的转译速度，避免 QEMU 模拟器导致的假死与报错。
- **精细化资源配额：** 针对 16G 内存的 Mac mini 定制资源限制（6G 软保留，12G 硬上限），既喂饱宝塔高并发需求，又确保宿主机 macOS 绝对流畅。

---

## 💻 二、 宿主机底层环境准备

在正式部署前，必须优化 Mac 的 Docker Desktop 底层引擎设置：

1. **启用 Rosetta 转译：**打开 `Docker Desktop` -&gt; 点击右上角 `Settings (设置齿轮)` -&gt; `General` -&gt; 务必勾选 **"Use Rosetta for x86/amd64 emulation on Apple Silicon"**。
2. **关闭本地冲突端口：**Host 模式要求端口独占。请确保 Mac 宿主机本机没有通过 Homebrew 或官方安装包运行原生的 Nginx(80)、MySQL(3306) 或 Redis(6379)。 *(若有运行，请提前执行如 `brew services stop mysql` 等命令关闭本地服务)*。

---

## 📂 三、 项目工作区搭建

打开 Mac 的 **终端 (Terminal)**，依次执行以下命令创建标准化企业级项目目录：

```bash
# 1. 创建专门的项目根目录及数据挂载点
mkdir -p ~/bt-server/wwwroot ~/bt-server/backup

# 2. 进入工作区
cd ~/bt-server

# 3. 创建声明式配置文件
touch docker-compose.yml

```

---

## 📄 四、 声明式配置文件 (`docker-compose.yml`)

请将以下完整的企业级配置代码写入 `~/bt-server/docker-compose.yml` 文件中：

```yaml
version: '3.8'

services:
  baota:
    image: ubuntu:22.04
    container_name: bt-mac-mini
    restart: always
    privileged: true
    network_mode: host
    
    # 💾 针对 16G Mac 极致释放性能的资源配额管理
    deploy:
      resources:
        limits:
          cpus: '6.0'       # 允许宝塔最多使用 6 个 CPU 核心
          memory: 12g      # 限制容器最大内存上限为 12G，防止极端高并发导致宿主机死机
        reservations:
          memory: 6g       # 容器启动时保底软保留 6G 内存
          
    volumes:
      # ⚡ :cached 机制极其关键：解决跨系统文件 IO 损耗
      - ~/bt-server/wwwroot:/www/wwwroot:cached
      - ~/bt-server/backup:/www/backup
      
    environment:
      - TZ=Asia/Shanghai   # 强制定制容器内部为北京时间
      
    # 🚀 首次启动自动初始化标准的 Linux 企业依赖环境
    command: >
      /bin/bash -c "
      apt-get update && 
      apt-get install -y wget curl sudo ufw lsb-release init && 
      tail -f /dev/null
      "

```

---

## 🚀 五、 容器启动与宝塔官方 LTS 脚本安装

### 1. 编排并后台启动容器

在 `~/bt-server` 目录下执行：

```bash
docker compose up -d

```

*(首次启动会自动下载官方纯净版 Ubuntu 22.04 ARM64 基础镜像并初始化，预计耗时 1 分钟)*

### 2. 执行宝塔官方正版 LTS 脚本

容器状态显示为 `Running` 后，直接向容器注入宝塔官方正版长期支持版（LTS）安装指令：

```bash
docker exec -it bt-mac-mini /bin/bash -c "\$(curl -sSO https://bt.cn && wget -O install_lts.sh https://bt.cn && bash install_lts.sh ed8484bec)"

```

*提示输入 `y/n` 时，请输入 **`y`** 并回车。*

### 3. 安全凭证召回指令

安装完成后，终端会打印出高强度的独立随机端口和安全入口。若不慎丢失，可随时运行以下指令重现：

```bash
docker exec -it bt-mac-mini bt default

```

> **访问示例：**输出结果类似：`http://localhost:32451/b8a2c1d0`。直接复制该完整地址至 Mac 浏览器即可登录面板。

---

## ⚙️ 六、 宝塔面板内“ARM 架构专属”黄金软件选型

登录宝塔面板后，进入 **软件商店** 安装 LNMP 技术栈，必须严格遵守以下针对 Apple Silicon 芯片优化的选型铁律：

### 1. 组件黄金搭配

- **Nginx：** 推荐 **1.24** 或 **1.26** -&gt; **必须选择“极速安装 (RPM)”**。
- **MySQL：** 强烈推荐 **8.0** -&gt; **必须选择“极速安装 (RPM)”**。 
    - *原因：* MySQL 8.0 针对 ARM64 架构（原子操作与内存屏障）进行了底层重构，运行效率远超 5.7。
- **PHP：** 推荐 **8.1 / 8.2 / 8.3** -&gt; **必须选择“极速安装 (RPM)”**。 
    - *原因：* 新版 PHP 完美发挥 M 系列芯片极强的单核指令集效率，JIT（即时编译）在 ARM64 下吞吐量极佳。

### ⚠️ 生产铁律

**绝对禁止在面板内点击“编译安装（Compiled）”**！在 Mac 容器虚拟化环境下，编译安装会因缺乏完整的 Linux 内核头文件支持，导致在编译 OpenSSL 或 Swoole 扩展时 100% 报错中断。

---

## ⚡ 七、 企业级生产力环境专项调优

得益于配置文件给出的 12G 内存上限，在环境安装完成后，请立即进行如下组件级优化，以压榨出企业级吞吐量：

### 1. MySQL 8.0 大规格性能释放

- **操作路径：** 软件商店 -&gt; MySQL 8.0 -&gt; 设置 -&gt; 性能调整。
- **参数调优：**
    - 将优化方案下拉框从“默认”直接切换为 **“4-8GB内存”**。
    - 宝塔会自动将 `innodb_buffer_pool_size`（InnoDB 缓冲池）提升至 **`4096MB` (4G)** 左右。
    - *效果：* 本地数千万条数据的复杂连表查询与热数据将全部常驻于 Mac 内存，压测响应速度缩短至微秒级。

### 2. PHP-FPM 高并发进程池加固

- **操作路径：** 软件商店 -&gt; 对应的 PHP 版本 -&gt; 设置 -&gt; 性能调整。
- **参数调优：**
    - **运行模式：** 选择 `dynamic` (动态模式)。
    - **max\_children (最大子进程数)：** 调整为 `80`。
    - **start\_servers (起始进程数)：** 调整为 `10`。
    - **min\_spare\_servers (最小空闲数)：** 调整为 `10`。
    - **max\_spare\_servers (最大空闲数)：** 调整为 `30`。
    - *效果：* 本地轻松扛住 1000+ QPS 的高频接口联调压测，充分吃满 Mac mini 的多核多线程优势。

---

## 💾 八、 日常运维与生命周期管理

此架构已完全声明式固化，后续对宝塔容器的维护无需重复安装，请在 `~/bt-server` 目录下使用标准 Docker 命令管理：

- **启动环境：** `docker compose start` (秒级恢复所有网站及数据库服务)
- **停止环境：** `docker compose stop` (释放内存资源回到 macOS)
- **查看实时日志：** `docker logs -f bt-mac-mini`
- **异地容灾：** 本地网站源码保存在 Mac 宿主机的 `~/bt-server/wwwroot` 中，宝塔定时备份保存在 `~/bt-server/backup` 中，可直接配合 iCloud、OneDrive 或坚果云实现自动化企业级云端异地备份。