# 文件管理：提权 + 归属 + 权限对话框 — 实施计划

| 项 | 内容 |
|----|------|
| 设计文档 | [2026-06-01-files-root-ownership-ui-design.md](../specs/2026-06-01-files-root-ownership-ui-design.md) |
| 日期 | 2026-06-01 |

## 涉及文件（预估）

| 层 | 文件 | 变更 |
|----|------|------|
| 基础设施 | `server/infrastructure/ssh/remote_shell.py` | **新建** 统一 `exec_remote_command` + elevation |
| 基础设施 | `server/infrastructure/ssh/remote_archive.py` | 迁出 fallback 到 remote_shell |
| 基础设施 | `server/infrastructure/ssh/asyncssh_pool.py` | `remote_write_bytes` 对齐 elevation |
| 工具 | `server/utils/unix_ls.py` | **新建** perms → mode_octal |
| API | `server/api/sync_v2.py` | browse 扩展字段；chmod 扩展 chown |
| API | `server/api/servers.py` | 可选 `GET .../files-capability` |
| 领域 | `server/domain/models/server.py` | 可选 `files_elevation` 列 |
| 前端类型 | `frontend/src/types/api.ts` | `FileEntry` + `FileChmodRequest` |
| 前端 API | `frontend/src/api/fileBrowse.ts` | 映射新字段 |
| 前端页面 | `frontend/src/pages/FilesPage.vue` | 归属列、右键对话框 |
| 前端组件 | `frontend/src/components/FilePermissionDialog.vue` | **新建** |
| 前端工具 | `frontend/src/utils/fileMode.ts` | 展示辅助（tooltip） |
| 运维 | `docs/deploy/nexus-files-sudoers.example` | **新建** |
| 测试 | `tests/test_file_permissions.py` | browse 解析、chmod 校验 |

## 实现步骤

1. **remote_shell**：实现 `FilesElevation`、`exec_remote_command`、从 `remote_archive` 抽 fallback。
2. **browse**：后端返回 `owner`/`group`/`mode_octal`；前端「归属」列 + tooltip。
3. **FilePermissionDialog**：预设、八进制、chown；对接扩展 `POST /sync/chmod`。
4. **file-ops / delete / mkdir**：接入 `exec_remote_command`。
5. **files-capability** + sudoers 示例文档。
6. **服务器 `files_elevation`**（若本期做 DB 字段则 migration，否则先用 settings 键）。
7. **pytest** + `ruff` + 本地 browse/chmod 手测。
8. **changelog** + 审计登记。

## 依赖与配置

- 目标机：`/etc/sudoers.d/nexus-files`（运维手动，模板见 deploy 示例）。
- 无 `.env` 变更；可选 `NEXUS_FILES_ELEVATION_DEFAULT=auto_sudo`（二期）。

## 测试要点

- mock SSH：`permission denied` → 第二次带 `sudo -n`。
- browse 解析含空格文件名、符号链接。
- chmod 400/755、chown `www:www`、非法 owner 拒绝。
- 前端对话框预设与目录/文件类型过滤。

## 回滚

- 后端：还原 `sync_v2.py` browse/chmod；删除 `remote_shell.py`，恢复 archive 内联 fallback。
- 前端：隐藏归属列，恢复旧 chmod 单输入框。
- DB：若新增 `files_elevation` 列，down migration 删除列。

## 部署

- 后端 `scp` + `supervisorctl restart nexus`
- 前端 `deploy/deploy-frontend.sh`
- 生产验证：server_id=30 路径下 chmod 644 → 列表显示 `www`