前言
在使用 VSCode Remote-SSH 连接 FNOS 时，可能会遇到普通 SSH 可以登录，但 VSCode 一直连接失败、卡在安装 VSCode Server、无法创建远程目录等问题。
**这类问题的一个常见原因是：**FNOS 用户没有标准的、可写的用户目录。
VSCode Remote-SSH 在连接远程主机时，会在远程用户的家目录下创建：
~/.vscode-server
**如果用户没有正确的 **$HOME 目录，或者该目录不可写，VSCode Server 就无法正常安装，从而导致 Remote-SSH 连接失败。
本文记录一种在 FNOS 上修复用户目录，并为 VSCode Remote-SSH 准备运行环境的方法。
一、本文示例环境说明
为了方便说明，本文使用以下示例信息：
FNOS 用户名：**
FNOS 主机名：**Nas
用户组：Users
目标用户目录：/vol2/1000/home/**
实际操作时，请根据自己的环境替换。
**如果你的 FNOS 用户名不是 ****，请将文中的：
**
替换成你自己的 FNOS 用户名。
**例如你的用户名是 **admin，则把：
/vol2/1000/home/**
改成：
/vol2/1000/home/admin
**如果你的 FNOS 主机名不是 ****Nas，请将文中的：
**Nas
替换成你自己的 FNOS 主机名或 FNOS 的局域网 IP。
例如：
192.168.1.100
**如果你的数据盘路径不是 **/vol2/1000，请将文中的：
/vol2/1000
替换成你自己的 FNOS 数据盘路径。
可以使用下面命令查看常见挂载路径：
df -h
二、问题现象
在 FNOS 上使用某个用户登录 SSH 后，发现用户目录存在异常。
执行：
getent passwd **
**其中 **** 需要替换成你自己的 FNOS 用户名。
示例输出：
**:x:1000:1001::/home/**:/bin/bash
可以看到该用户的家目录被设置为：
/home/**
但是在某些 FNOS 环境中，这个目录可能不存在，或者当前用户无法正常写入。
当 VSCode Remote-SSH 尝试连接时，它需要在远程用户目录下创建：
~/.vscode-server
如果用户目录不存在或不可写，就会导致连接失败。
三、确认用户和用户组信息
首先查看当前用户的 UID、GID 和所属用户组。
命令格式：
id 你的用户名
示例：
id **
示例输出：
uid=1000(**) gid=1001(Users) groups=1001(Users),1000(Administrators)
从输出中可以看到：
用户名：**
主用户组：Users
这里需要特别注意，很多 NAS 系统不会给用户创建同名用户组。
也就是说，虽然用户名是：
**
但用户组不一定也是：
**
如果直接执行：
sudo chown -R **:** /home/**
可能会出现：
chown: invalid group: ‘**:**’
**这是因为系统里没有名为 **** 的用户组。
**正确做法是根据 **id 用户名 的输出，找到用户的主用户组。
例如这里的主用户组是：
Users
那么后续就应该使用：
**:Users
**如果你的用户名是 **admin，主用户组是 Users，则应该使用：
admin:Users
**如果你的主用户组不是 **Users，请替换成你自己系统中实际显示的用户组名称。
四、选择新的用户目录位置
对于 FNOS 这类 NAS 系统，建议把用户目录放到数据盘，而不是系统分区。
本文示例目标用户目录为：
/vol2/1000/home/**
其中：
/vol2/1000
是数据盘路径，需要根据自己的 FNOS 实际情况修改。
**
是用户名，需要替换成你自己的 FNOS 用户名。
**如果你的用户名是 **admin，并且数据盘路径也是 /vol2/1000，那么目标用户目录可以写成：
/vol2/1000/home/admin
**如果你的数据盘路径是 **/vol1/1000，用户名是 admin，那么目标用户目录可以写成：
/vol1/1000/home/admin
可以通过下面命令查看自己的磁盘挂载路径：
df -h
五、创建新的用户目录
命令格式如下：
sudo mkdir -p /你的数据盘路径/home/你的用户名
sudo chown -R 你的用户名:你的用户组 /你的数据盘路径/home/你的用户名
sudo chmod 755 /你的数据盘路径/home/你的用户名
本文示例命令：
sudo mkdir -p /vol2/1000/home/**
sudo chown -R **:Users /vol2/1000/home/**
sudo chmod 755 /vol2/1000/home/**
请根据自己的环境替换：
** -> 你的 FNOS 用户名
Users -> 你的用户主组
/vol2/1000 -> 你的数据盘路径
**例如你的用户名是 **admin，用户组是 Users，数据盘路径是 /vol1/1000，则命令应改为：
sudo mkdir -p /vol1/1000/home/admin
sudo chown -R admin:Users /vol1/1000/home/admin
sudo chmod 755 /vol1/1000/home/admin
然后检查目录权限：
ls -ld /vol2/1000/home/**
同样需要把路径替换成你自己的目标用户目录。
示例输出：
drwxr-xr-x+ 2 ** Users 4096 Jun 10 16:39 /vol2/1000/home/**
这里需要重点确认两点：
** Users
表示目录所有者和用户组正确。
drwxr-xr-x
表示目录具备基本访问权限。
六、尝试修改用户 HOME 目录
**一般情况下，可以直接使用 **usermod 修改用户目录。
命令格式：
sudo usermod -d /你的数据盘路径/home/你的用户名 -s /bin/bash 你的用户名
本文示例：
sudo usermod -d /vol2/1000/home/** -s /bin/bash **
请将其中的：
/vol2/1000/home/**
替换成你的目标用户目录。
将：
**
替换成你的 FNOS 用户名。
例如：
sudo usermod -d /vol1/1000/home/admin -s /bin/bash admin
如果执行成功，可以直接跳到第九部分检查结果。
但是如果当前用户正在运行进程，可能会出现如下错误：
usermod: user ** is currently used by process 108973
**这表示该用户当前还有进程正在运行，系统暂时不允许通过 **usermod 修改用户信息。
七、查看当前用户正在运行的进程
切换到 root：
sudo -i
查看指定用户正在运行的进程。
命令格式：
pgrep -u 你的用户名 -a
本文示例：
pgrep -u ** -a
示例输出：
3961 /usr/local/bin/gitea web
108973 /lib/systemd/systemd --user
108974 (sd-pam)
108994 sshd: **@pts/0,pts/1
108995 -bash
108997 /usr/lib/openssh/sftp-server
108998 -bash
109033 top
如果这个用户下不仅有当前 SSH 会话，还有其他服务进程，例如：
/usr/local/bin/gitea web
就不建议直接执行：
pkill -u 用户名
因为这样会结束该用户下的所有进程，可能会影响正在运行的服务。
**更稳妥的方式是手动修改 **/etc/passwd 中的用户目录。
八、使用 vipw 安全修改 /etc/passwd
**推荐使用 **vipw 修改用户信息。
在 root 用户下执行：
vipw
找到类似这一行：
**:x:1000:1001::/home/**:/bin/bash
**这里的 **** 是示例用户名。
将其中的用户目录部分从：
/home/**
修改为你的新用户目录。
本文示例修改为：
/vol2/1000/home/**
修改后的完整行类似：
**:x:1000:1001::/vol2/1000/home/**:/bin/bash
**如果你的用户名是 **admin，目标目录是 /vol1/1000/home/admin，则应类似：
admin:x:1000:1001::/vol1/1000/home/admin:/bin/bash
保存并退出。
vipw 会对 /etc/passwd 进行安全编辑，避免多个进程同时修改用户数据库。
九、如果没有 vipw，可以手动编辑 /etc/passwd
**如果系统中没有 **vipw，也可以使用 nano 手动修改。
建议先备份：
cp /etc/passwd /etc/passwd.bak
然后编辑：
nano /etc/passwd
找到当前用户对应的一行。
示例：
**:x:1000:1001::/home/**:/bin/bash
把原来的家目录：
/home/**
改成新的目标目录。
示例：
**:x:1000:1001::/vol2/1000/home/**:/bin/bash
保存退出。
注意：只修改这一行中的家目录字段，不要随意修改 UID、GID、用户名和 shell 字段。
十、确认修改是否成功
执行：
getent passwd **
**其中 **** 替换成你自己的用户名。
如果输出类似：
**:x:1000:1001::/vol2/1000/home/**:/bin/bash
说明用户目录已经成功修改。
重点确认这一段已经变成你的新用户目录：
/vol2/1000/home/**
十一、重新登录 SSH
退出 root：
exit
再退出当前 SSH 会话：
exit
然后重新连接 FNOS。
如果使用主机名：
ssh **@**Nas
如果使用 IP：
ssh **@192.168.1.100
请将：
**
替换成你的 FNOS 用户名。
将：
**Nas
替换成你的 FNOS 主机名。
将：
192.168.1.100
替换成你的 FNOS 局域网 IP。
十二、检查新的 HOME 是否生效
重新登录后执行：
whoami
echo $HOME
pwd
理想输出类似：
**
/vol2/1000/home/**
/vol2/1000/home/**
**如果你的用户名是 **admin，目标目录是 /vol1/1000/home/admin，则理想输出应类似：
admin
/vol1/1000/home/admin
/vol1/1000/home/admin
**只要 **echo $HOME 显示为你设置的新用户目录，就说明新的 HOME 已经生效。
十三、测试 VSCode Server 目录是否可创建
**VSCode Remote-SSH 会在远程用户目录下创建 **.vscode-server，因此需要手动测试：
mkdir -p ~/.vscode-server
ls -ld ~/.vscode-server
如果没有报错，并且输出路径位于你的新用户目录下，例如：
/vol2/1000/home/**/.vscode-server
说明当前用户已经可以正常写入 VSCode Server 所需目录。
这一步非常关键。
只要下面命令可以正常执行：
mkdir -p ~/.vscode-server
且没有权限错误，VSCode Remote-SSH 的远程目录问题基本就解决了。
十四、Windows 端 SSH 配置建议
在 Windows 上打开 SSH 配置文件：
C:\Users\你的Windows用户名\.ssh\config
添加 FNOS 主机配置。
模板如下：
Host 自定义连接名
HostName 你的FNOS_IP或主机名
User 你的FNOS用户名
Port 22
ServerAliveInterval 30
ServerAliveCountMax 3
示例：
Host **Nas
HostName 192.168.1.100
User **
Port 22
ServerAliveInterval 30
ServerAliveCountMax 3
其中：
Host **Nas
是你在 VSCode 里看到的连接名称，可以自定义。
HostName 192.168.1.100
需要改成你的 FNOS IP 或主机名。
User **
需要改成你的 FNOS 用户名。
配置完成后，在 VSCode 中执行：
Remote-SSH: Connect to Host...
然后选择你刚才配置的连接名。
十五、VSCode Remote-SSH 设置建议
**如果之前连接失败过，可以在 VSCode 的 **settings.json 中添加以下配置：
{
"remote.SSH.useLocalServer": false,
"remote.SSH.remotePlatform": {
"**Nas": "linux"
},
"remote.SSH.serverInstallPath": {
"**Nas": "/vol2/1000/home/**/.vscode-server"
}
}
这段配置中有两个地方需要改成你自己的内容。
第一处是连接名：
"**Nas": "linux"
**这里的 ****Nas 要和你 SSH config 里的 Host 名称保持一致。
例如你的 SSH config 是：
Host fnos
那么这里就应该写成：
"remote.SSH.remotePlatform": {
"fnos": "linux"
}
第二处是 VSCode Server 安装路径：
"**Nas": "/vol2/1000/home/**/.vscode-server"
**这里也要把 ****Nas 改成你的 SSH config 连接名，把路径改成你的实际用户目录。
例如：
{
"remote.SSH.useLocalServer": false,
"remote.SSH.remotePlatform": {
"fnos": "linux"
},
"remote.SSH.serverInstallPath": {
"fnos": "/vol1/1000/home/admin/.vscode-server"
}
}
配置说明：
"remote.SSH.useLocalServer": false
用于关闭本地服务模式，减少 Windows 环境下的兼容问题。
"remote.SSH.remotePlatform": {
"fnos": "linux"
}
用于明确告诉 VSCode，远程主机是 Linux 系统。
"remote.SSH.serverInstallPath": {
"fnos": "/vol1/1000/home/admin/.vscode-server"
}
用于指定 VSCode Server 安装目录，避免它写入错误路径。
十六、清理旧的 VSCode Server 目录
如果之前连接失败过，可以清理残留目录后重新连接：
rm -rf ~/.vscode-server
rm -rf ~/.vscode-remote
然后重新在 VSCode 中连接 FNOS。
**如果你的 **$HOME 已经正确指向新目录，那么这里的 ~ 就会自动对应你的新用户目录。
十七、完整命令汇总
下面是本次操作中最关键的命令模板。
查看用户信息：
id 你的用户名
getent passwd 你的用户名
创建新的用户目录：
sudo mkdir -p /你的数据盘路径/home/你的用户名
sudo chown -R 你的用户名:你的用户组 /你的数据盘路径/home/你的用户名
sudo chmod 755 /你的数据盘路径/home/你的用户名
查看目录权限：
ls -ld /你的数据盘路径/home/你的用户名
**尝试使用 **usermod 修改用户目录：
sudo usermod -d /你的数据盘路径/home/你的用户名 -s /bin/bash 你的用户名
如果提示用户正在被进程使用，切换 root：
sudo -i
查看该用户进程：
pgrep -u 你的用户名 -a
**使用 **vipw 修改用户目录：
vipw
**将 **/etc/passwd 中该用户的家目录字段从旧路径改成新路径。
例如从：
**:x:1000:1001::/home/**:/bin/bash
改为：
**:x:1000:1001::/vol2/1000/home/**:/bin/bash
检查修改结果：
getent passwd 你的用户名
重新登录后检查：
whoami
echo $HOME
pwd
mkdir -p ~/.vscode-server
ls -ld ~/.vscode-server
十八、总结
本次 VSCode Remote-SSH 连接 FNOS 失败的核心原因是：
远程用户没有正确、可写的 HOME 用户目录
解决思路是：
- 确认 FNOS 用户名和用户组；
- 在 FNOS 数据盘创建新的用户目录；
- 将目录所有者设置为当前用户和对应用户组；
- 修改用户的 HOME 路径；
- 重新登录 SSH；
- **确认 **
$HOME 已经指向新目录；
- **测试 **
.vscode-server 是否可以创建；
- 重新使用 VSCode Remote-SSH 连接。
对于 FNOS 这类 NAS 系统，建议将用户目录放在数据盘路径下，例如：
/vol2/1000/home/你的用户名
这样既可以避免占用系统分区，也能保证 VSCode Remote-SSH 有稳定的写入空间。
最终，只要下面命令能够成功执行：
mkdir -p ~/.vscode-server
并且没有权限错误，VSCode Remote-SSH 基本就具备正常连接的条件了。
