# HLCC-ENTERPRISE-INSTALL-GUIDE-AWEN

标题：光湖代码频道企业服务器离线部署说明
编号：HLCC-DOC-ENTERPRISE-INSTALL-20260724-001
收件人：光湖团队技术主控 Awen 及其部署人格体
状态：可执行安装稿
适用版本：HLCC 离线包 v16.0.1（以离线包内 `manifest.json` 的版本为准）

## 0. 先确认边界

本包部署的是“光湖代码频道”，不是第五域旧实例，也不是 Gitea 服务。企业服务器应保留企业代码频道自己的数据目录、配置目录和备份目录；不要把企业数据目录指向个人第五域目录。

离线包应从微信收到后先做完整性核验，再安装。安装期间不需要访问海外下载地址；运行时默认关闭在线更新、镜像和动作任务，版本更新由光湖侧准备新的离线包并通过受控变更进入。

## 1. 安装前检查

在企业服务器上准备：

1. Linux x86_64 主机，systemd 可用。
2. 一个专用运行用户，例如 `guanghu`；禁止使用 root 运行服务。
3. 一个专用状态目录，例如 `/var/lib/guanghu/hlcc-enterprise`，权限为运行用户可读写、其他用户不可读。
4. 一个专用反向代理入口，例如 `https://代码频道域名/`。如果挂在已有域名的子路径，确保 `ROOT_URL` 与实际子路径完全一致。
5. 企业侧已有备份位置。首次启动前先备份状态目录和反向代理配置。

不要把任何 API 密钥、管理员密码或个人身份数据库写入离线包、提交记录或安装日志。密钥应由企业侧的密钥管理方式注入，安装文档只记录变量名和权限要求。

## 2. 离线包验收

在离线包目录执行：

```text
sha256sum -c manifest.sha256
```

然后确认 `manifest.json`、签名文件和程序文件的版本一致。若校验失败、版本字段缺失或来源不明，停止安装并把校验结果回传给光湖团队，不要强行启动。

## 3. 安装顺序

以离线包内的安装器为准，顺序固定为：

1. 创建 `guanghu` 用户、状态目录、日志目录和备份目录。
2. 将离线包复制到企业服务器的受控暂存目录，设置为仅管理员可读。
3. 运行离线安装器；安装器应创建独立的 `app.ini`、SQLite/数据库目录、仓库目录和 systemd 单元。
4. 将企业域名、监听地址、端口、`ROOT_URL` 和备份路径填入企业侧配置，不复制个人第五域的配置文件。
5. 启动服务并等待健康检查返回 `ready=true`。
6. 通过企业反向代理访问首页、登录页和一个公开仓库页，再进行一次人工登录验收。

## 4. 企业侧配置要求

必须保持以下策略：

```text
APP_NAME = 光湖代码频道
RUN_MODE = prod
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = false
OFFLINE_MODE = true
镜像/在线更新 = 关闭
动作任务 = 关闭（除非企业侧另有审批）
SSH 入口 = 按企业网络策略决定；不需要时关闭
```

企业实例的 `ROOT_URL` 必须使用企业实际入口；如果通过 `/code/` 子路径发布，必须写成 `https://企业域名/code/`，不能沿用个人实例的 `https://guanghulab.com/code/`。

## 5. 首次登录与权限

企业实例首次登录由 Awen 按企业身份策略完成。不要复制冰朔个人账号的密码哈希、会话、令牌或个人仓库数据。部署人格体只做安装、健康检查、备份和回滚，不替人创建长期令牌。

建议先创建一个企业管理员账号，再创建企业团队账号；默认仓库设为私有，确需公开时由人类审批。所有写入操作应保留提交者、时间、提交号和回滚点。

## 6. 验收清单

安装完成后逐项记录结果：

- [ ] `systemctl is-active` 为 `active`。
- [ ] 健康端点返回 `ok=true`、`ready=true`。
- [ ] 首页 HTTP 200，页面标题显示“光湖代码频道”。
- [ ] 登录页可打开，人工账号可以登录。
- [ ] 新建一个测试仓库并提交一个测试文件。
- [ ] 从浏览器读取仓库、提交记录和文件内容均正常。
- [ ] 重启服务后仓库仍存在，且没有触发在线下载。
- [ ] 备份能够生成，抽样恢复到临时目录后可读取。
- [ ] 旧第五域实例、个人仓库和企业实例之间没有数据目录交叉引用。

验收记录请回写到企业实例的部署记录中，并把版本、主机编号、入口域名、提交号和回滚点发回光湖团队。

## 7. 回滚

若首页、登录、仓库读取或数据迁移任一项失败：

1. 停止企业新实例。
2. 保留失败日志和校验结果，不覆盖原备份。
3. 恢复安装前的状态目录与反向代理配置。
4. 确认旧服务健康后再对外开放。
5. 将失败阶段和最后一条日志摘要回传，不要重复执行破坏性迁移。

## 8. 光湖侧回传格式

```text
实例：企业光湖代码频道
离线包版本：
manifest SHA256：
服务器编号：
入口 URL：
服务状态：
健康检查：
测试仓库/提交号：
备份位置：
回滚点：
异常摘要：
```

这份说明只负责企业实例的安装与验收；企业业务仓库、密钥和人员权限由企业侧自行管理。版本升级必须使用新的、经过校验的离线包，先在测试实例验收，再安排生产窗口。